rfc8881xml2.original.xml | rfc8881.xml | |||
---|---|---|---|---|
<?xml version="1.0" encoding="US-ASCII"?> | <?xml version='1.0' encoding='utf-8'?> | |||
<!DOCTYPE rfc SYSTEM "rfc2629.dtd"> | <!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent"> | |||
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?> | <rfc xmlns:xi="http://www.w3.org/2001/XInclude" category="std" docName="draft-ie | |||
tf-nfsv4-rfc5661sesqui-msns-04" number="8881" obsoletes="5661" ipr="pre5378Trust | ||||
<?rfc toc="yes"?> | 200902" updates="" submissionType="IETF" consensus="true" xml:lang="en" tocInclu | |||
<?rfc tocompact="yes"?> | de="true" tocDepth="2" symRefs="false" sortRefs="false" version="3"> | |||
<?rfc tocdepth="2"?> | ||||
<?rfc symrefs="no"?> | ||||
<?rfc sortrefs="no" ?> | ||||
<?rfc compact="yes" ?> | ||||
<?rfc subcompact="no" ?> | ||||
<?rfc rfcedstyle="yes" ?> | ||||
<rfc | ||||
category="std" | ||||
docName="draft-ietf-nfsv4-rfc5661sesqui-msns-04" | ||||
obsoletes="5661" | ||||
ipr="pre5378Trust200902"> | ||||
<front> | <!-- xml2rfc v2v3 conversion 2.41.0 --> | |||
<title abbrev="NFSv4.1 with Namespace Update "> | <front> | |||
<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"/> | ||||
<author fullname="David Noveck" | <author fullname="David Noveck" initials="D." surname="Noveck" role="editor" | |||
initials="D." | > | |||
surname="Noveck" role="editor"> | <organization abbrev="NetApp">NetApp</organization> | |||
<organization abbrev="NetApp">NetApp</organization> | <address> | |||
<address> | <postal> | |||
<postal> | <street>1601 Trapelo Road, Suite 16</street> | |||
<street>1601 Trapelo Road, Suite 16</street> | <city>Waltham</city> | |||
<city>Waltham</city> | <region>MA</region> | |||
<region>MA</region> | <code>02451</code> | |||
<code>02451</code> | <country>United States of America</country> | |||
<country>USA</country> | </postal> | |||
</postal> | <phone>+1-781-768-5347</phone> | |||
<phone>+1-781-768-5347</phone> | <email>dnoveck@netapp.com</email> | |||
<email>dnoveck@netapp.com</email> | </address> | |||
</address> | ||||
</author> | </author> | |||
<author initials='C.' surname='Lever' | <author initials="C." surname="Lever" fullname="Charles Lever"> | |||
fullname = 'Charles Lever'> | <organization abbrev="ORACLE"> | |||
<organization abbrev='ORACLE'> | ||||
Oracle Corporation | Oracle Corporation | |||
</organization> | </organization> | |||
<address> | <address> | |||
<postal> | <postal> | |||
<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="August" year="2020"/> | ||||
<date year="2020"/> | ||||
<area>Transport</area> | <area>Transport</area> | |||
<workgroup>NFSv4</workgroup> | <workgroup>NFSv4</workgroup> | |||
<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. | |||
</t> | </t> | |||
<t> | <t> | |||
This document obsoletes RFC5661. It substantially revises the treatment | This document obsoletes RFC 5661. It substantially revises the treatment | |||
of features relating to multi-server namespace, superseding the | of features relating to multi-server namespace, superseding the | |||
description of those features appearing in RFC5661. | description of those features appearing in RFC 5661. | |||
</t> | </t> | |||
</abstract> | </abstract> | |||
</front> | ||||
</front> | <middle> | |||
<section anchor="intro" numbered="true" toc="default"> | ||||
<middle> | <name>Introduction</name> | |||
<section anchor="intro_the_document" numbered="true" toc="default"> | ||||
<section anchor="intro" title="Introduction" > | <name>Introduction to This Update</name> | |||
<section anchor="intro_the_document" | <t> | |||
title="Introduction to this Update"> | ||||
<t> | ||||
Two important features previously defined in minor version 0 but | Two important features previously defined in minor version 0 but | |||
never fully addressed in minor version 1 are trunking, the | never fully addressed in minor version 1 are trunking, which is the | |||
simultaneous use of | simultaneous use of | |||
multiple connections between a client and server, potentially to | multiple connections between a client and server, potentially to | |||
different network addresses, and transparent state migration, which | different network addresses, and Transparent State Migration, which | |||
allows a file system to be transferred between servers in a way that | allows a file system to be transferred between servers in a way that | |||
provides to the client the ability to maintain its existing locking | provides to the client the ability to maintain its existing locking | |||
state across the transfer. | state across the transfer. | |||
</t> | </t> | |||
<t> | <t> | |||
The revised description of the NFS version 4 minor version 1 | The revised description of the NFS version 4 minor version 1 | |||
(NFSv4.1) protocol presented in this update is necessary to enable | (NFSv4.1) protocol presented in this update is necessary to enable | |||
full use of these features together with other multi-server namespace | full use of these features together with other multi-server namespace | |||
features. This document is in the form of an updated description of | features. This document is in the form of an updated description of | |||
the NFSv4.1 protocol previously defined in RFC5661 | the NFSv4.1 protocol previously defined in RFC 5661 | |||
<xref target="RFC5661"/>. | <xref target="RFC5661" format="default"/>. | |||
RFC5661 is obsoleted by this document. However, the update has a | RFC 5661 is obsoleted by this document. However, the update has a | |||
limited scope and is focused on enabling full use of trunking and | limited scope and is focused on enabling full use of trunking and | |||
transparent state migration. The need for these changes is discussed | Transparent State Migration. The need for these changes is discussed | |||
in Appendix A. Appendix B describes the specific changes made to | in <xref target="NEED"/>. <xref target="CHG"/> describes the specific cha | |||
nges made to | ||||
arrive at the current text. | arrive at the current text. | |||
</t> | </t> | |||
<t> | <t> | |||
This limited-scope update replaces the current NFSv4.1 RFC with the | This limited-scope update replaces the current NFSv4.1 RFC with the | |||
intention of providing an authoritative and complete specification, the | intention of providing an authoritative and complete specification, the | |||
motivation for which is discussed in | motivation for which is discussed in | |||
<xref target="I-D.roach-bis-documents"/>, | <xref target="I-D.roach-bis-documents" format="default"/>, | |||
addressing the issues within the scope of the update. However, it will | addressing the issues within the scope of the update. However, it will | |||
not address issues that are known but outside of this limited scope | not address issues that are known but outside of this limited scope | |||
as could expected by a full update of the protocol. Below are some | as could be expected by a full update of the protocol. Below are some | |||
areas which are known to need addressing in a future update of the | areas that are known to need addressing in a future update of the | |||
protocol. | protocol: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
Work needs to be done with regard to | <li> | |||
RFC8178 <xref target="RFC8178"/> which establishes NFSv4-wide | Work needs to be done with regard to RFC 8178 | |||
<xref target="RFC8178" format="default"/>, which establishes NFSv4-wide | ||||
versioning rules. As | versioning rules. As | |||
RFC5661 is currently inconsistent with | RFC 5661 is currently inconsistent with | |||
that document, changes are needed in order | that document, changes are needed in order | |||
to arrive at a situation in which there | to arrive at a situation in which there | |||
would be no need for RFC8178 to update the NFSv4.1 specification. | would be no need for RFC 8178 to update the NFSv4.1 specification. | |||
</t> | </li> | |||
<t> | <li> | |||
Work needs to be done with regard to | Work needs to be done with regard to RFC 8434 | |||
RFC8434 <xref target="RFC8434" />, which establishes the requirements | <xref target="RFC8434" format="default"/>, which establishes the requirem | |||
for pNFS layout types, which are not clearly defined in | ents | |||
RFC5661. When that | for parallel NFS (pNFS) layout types, which are not clearly defined in | |||
RFC 5661. When that | ||||
work is done and the resulting documents approved, | work is done and the resulting documents approved, | |||
the new NFSv4.1 specification document will provide a clear set | the new NFSv4.1 specification document will provide a clear set | |||
of requirements for layout types and a description of the file layout | of requirements for layout types and a description of the file layout | |||
type that conforms to those requirements. Other layout types will | type that conforms to those requirements. Other layout types will | |||
have their own specification documents that conforms to those | have their own specification documents that conform to those | |||
requirements as well. | requirements as well. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
Work needs to be done to address many errata reports relevant to | Work needs to be done to address many errata reports relevant to | |||
RFC 5661, other than errata report 2006 <xref target="Err2006"/>, | RFC 5661, other than errata report 2006 <xref target="Err2006" format="de fault"/>, | |||
which is addressed in this document. | which is addressed in this document. | |||
Addressing that report was not deferrable because of the | Addressing that report was not deferrable because of the | |||
interaction of the changes suggested there | interaction of the changes suggested there | |||
and the newly described handling of state and session migration. | and the newly described handling of state and session migration. | |||
<vspace blankLines="1"/> | </t> | |||
<t> | ||||
The errata reports that have been deferred and that will need to | The errata reports that have been deferred and that will need to | |||
be addressed in a later document include reports currently assigned | be addressed in a later document include reports currently assigned | |||
a range of statuses in the errata reporting system including reports | a range of statuses in the errata reporting system, including reports | |||
marked Accepted and those marked Hold For Document Update | marked Accepted and those marked Hold For Document Update | |||
because the change was | because the change was | |||
too minor to address immediately. | too minor to address immediately. | |||
<vspace blankLines="1"/> | </t> | |||
<t> | ||||
In addition, there is a set of other reports, including at least one | In addition, there is a set of other reports, including at least one | |||
in state Rejected, which will need to be addressed in a later document. | in state Rejected, that will need to be addressed in a later document. | |||
This will involve making changes to consensus decisions reflected | This will involve making changes to consensus decisions reflected | |||
in RFC 5661, in situation 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 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 | described in RFC 5661. | |||
in RFC 5661. | </t> | |||
<vspace blankLines="1"/> | <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 implementers 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"/>. | obsoletes RFC 5661 <xref target="RFC5661" format="default"/>. | |||
</t> | </t> | |||
<t> | </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"/>) 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"/> or to create a new document describing | <xref target="RFC7530" format="default"/> or to create a new document des cribing | |||
internationalization for all | internationalization for all | |||
NFSv4 minor versions and reference that document in the RFCs | NFSv4 minor versions and reference that document in the RFCs | |||
defining both NFSv4.0 and NFSv4.1. | defining both NFSv4.0 and NFSv4.1. | |||
</t> | </li> | |||
<t> | <li> | |||
There is a need for a revised treatment of security | There is a need for a revised treatment of security | |||
in NFSv4.1. The issues with the existing treatment are discussed in | in NFSv4.1. The issues with the existing treatment are discussed in | |||
<xref target="SECBAD"/>. | <xref target="SECBAD" format="default"/>. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Until the above work is done, there will not be a consistent set of | Until the above work is done, there will not be a consistent set of | |||
documents providing a description of the NFSv4.1 protocol and any | documents that provides a description of the NFSv4.1 protocol, and any | |||
full description would involve documents updating other documents | full description would involve documents updating other documents | |||
within the specification. The updates applied by | within the specification. The updates applied by | |||
RFC8434 <xref target="RFC8434"/> and RFC8178 <xref target="RFC8178"/> | RFC 8434 <xref target="RFC8434" format="default"/> and RFC 8178 | |||
to RFC5661 also apply to this specification, and will apply to | <xref target="RFC8178" format="default"/> | |||
to RFC 5661 also apply to this specification, and will apply to | ||||
any subsequent v4.1 specification until that work is done. | any subsequent v4.1 specification until that work is done. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="intro_the_protocol" | <section anchor="intro_the_protocol" numbered="true" toc="default"> | |||
<name>The NFS Version 4 Minor Version 1 Protocol</name> | ||||
title="The NFS Version 4 Minor Version 1 Protocol"> | <t> | |||
<t> | ||||
The NFS version 4 minor version 1 (NFSv4.1) protocol | The NFS version 4 minor version 1 (NFSv4.1) protocol | |||
is the second minor version of the NFS version 4 | is the second minor version of the NFS version 4 | |||
(NFSv4) protocol. The first minor version, NFSv4.0, is | (NFSv4) protocol. The first minor version, NFSv4.0, is | |||
now described in RFC 7530 <xref target="RFC7530" />. It generally | now described in RFC 7530 <xref target="RFC7530" format="default"/>. It g enerally | |||
follows the guidelines for minor versioning that are | follows the guidelines for minor versioning that are | |||
listed in Section 10 of RFC 3530. However, it | listed in Section <xref target="RFC3530" sectionFormat="bare" section="10" | |||
/> | ||||
of RFC 3530 <xref target="RFC3530" format="default"/>. However, it | ||||
diverges from guidelines 11 ("a client and server | diverges from guidelines 11 ("a client and server | |||
that support minor version X must support minor | that support minor version X must support minor | |||
versions 0 through X-1") and 12 ("no new features may be | versions 0 through X-1") and 12 ("no new features may be | |||
introduced as mandatory in a minor version"). These | introduced as mandatory in a minor version"). These | |||
divergences are due to the introduction of | divergences are due to the introduction of | |||
the sessions model for managing non-idempotent | the sessions model for managing non-idempotent | |||
operations and the RECLAIM_COMPLETE operation. | operations and the RECLAIM_COMPLETE operation. | |||
These two new features are infrastructural in | These two new features are infrastructural in | |||
nature and simplify implementation of existing and | nature and simplify implementation of existing and | |||
other new features. Making them anything but REQUIRED | other new features. Making them anything but <bcp14>REQUIRED</bcp14> | |||
would add undue complexity to protocol definition and | would add undue complexity to protocol definition and | |||
implementation. NFSv4.1 accordingly updates the | implementation. NFSv4.1 accordingly updates the | |||
<xref target="minor_versioning">minor versioning | <xref target="minor_versioning" format="default">minor versioning | |||
guidelines</xref>. | guidelines</xref>. | |||
</t> | </t> | |||
<t> | <t> | |||
As a minor version, NFSv4.1 is consistent with the overall | As a minor version, NFSv4.1 is consistent with the overall | |||
goals for NFSv4, but extends the protocol so as to | goals for NFSv4, but extends the protocol so as to | |||
better meet those goals, based on experiences with NFSv4.0. | better meet those goals, based on experiences with NFSv4.0. | |||
In addition, NFSv4.1 has adopted some additional goals, which | In addition, NFSv4.1 has adopted some additional goals, which | |||
motivate some of the major extensions in NFSv4.1. | motivate some of the major extensions in NFSv4.1. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Requirements Language"> | <section numbered="true" toc="default"> | |||
<t>The key words "MUST", "MUST NOT", | <name>Requirements Language</name> | |||
"REQUIRED", "SHALL", "SHALL NOT", | ||||
"SHOULD", "SHOULD NOT", "RECOMMENDED", | ||||
"MAY", and "OPTIONAL" in this document are to be | ||||
interpreted as described in <xref target="RFC2119">RFC 2119</xref>. | ||||
</t> | ||||
</section> | <t>The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14 | |||
>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL | ||||
NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp1 | ||||
4>RECOMMENDED</bcp14>", "<bcp14>MAY</bcp14>", and | ||||
"<bcp14>OPTIONAL</bcp14>" in this document are to be interpreted as descri | ||||
bed in | ||||
RFC 2119 <xref target="RFC2119"/>.</t> | ||||
<section anchor="scope_of_doc" title="Scope of This Document"> | </section> | |||
<t> | <section anchor="scope_of_doc" numbered="true" toc="default"> | |||
<name>Scope of This Document</name> | ||||
<t> | ||||
This document describes the NFSv4.1 protocol. With | This document describes the NFSv4.1 protocol. With | |||
respect to NFSv4.0, this document does not: | respect to NFSv4.0, this document does not: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
describe the NFSv4.0 protocol, except where needed | describe the NFSv4.0 protocol, except where needed | |||
to contrast with NFSv4.1. | to contrast with NFSv4.1. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
modify the specification of the NFSv4.0 protocol. | modify the specification of the NFSv4.0 protocol. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
clarify the NFSv4.0 protocol. | clarify the NFSv4.0 protocol. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
<section anchor="version4_goals" numbered="true" toc="default"> | ||||
</section> | <name>NFSv4 Goals</name> | |||
<section anchor="version4_goals" title="NFSv4 Goals"> | <t> | |||
<t> | ||||
The NFSv4 protocol is a further revision of the NFS protocol | The NFSv4 protocol is a further revision of the NFS protocol | |||
defined already by NFSv3 | defined already by NFSv3 | |||
<xref target="RFC1813" />. It retains | <xref target="RFC1813" format="default"/>. It retains | |||
the essential characteristics of previous versions: easy | the essential characteristics of previous versions: easy | |||
recovery; independence of transport protocols, operating systems, and | recovery; independence of transport protocols, operating systems, and | |||
file systems; simplicity; and good performance. NFSv4 has the following g oals: | file systems; simplicity; and good performance. NFSv4 has the following g oals: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
Improved access and good performance on the Internet | Improved access and good performance on the Internet | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
The protocol is designed to transit firewalls easily, perform well | The protocol is designed to transit firewalls easily, perform well | |||
where latency is high and bandwidth is low, and scale to very | where latency is high and bandwidth is low, and scale to very | |||
large numbers of clients per server. | large numbers of clients per server. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
Strong security with negotiation built into the protocol | Strong security with negotiation built into the protocol | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
The protocol builds on the work of the ONCRPC working group in | The protocol builds on the work of the ONCRPC working group in | |||
supporting the RPCSEC_GSS protocol. Additionally, the | supporting the RPCSEC_GSS protocol. Additionally, the | |||
NFSv4.1 protocol provides a mechanism to allow clients and | NFSv4.1 protocol provides a mechanism to allow clients and | |||
servers the ability to negotiate security and require clients and server s to | servers the ability to negotiate security and require clients and server s to | |||
support a minimal set of security schemes. | support a minimal set of security schemes. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
Good cross-platform interoperability | Good cross-platform interoperability | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
The protocol features a file system model that provides a useful, | The protocol features a file system model that provides a useful, | |||
common set of features that does not unduly favor one file system | common set of features that does not unduly favor one file system | |||
or operating system over another. | or operating system over another. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
Designed for protocol extensions | Designed for protocol extensions | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
The protocol is designed to accept standard extensions within a | The protocol is designed to accept standard extensions within a | |||
framework that enables and encourages backward compatibility. | framework that enables and encourages backward compatibility. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ul> | |||
</section> | </section> | |||
<section anchor="minor_version1_goals" title="NFSv4.1 Goals"> | <section anchor="minor_version1_goals" numbered="true" toc="default"> | |||
<t> | <name>NFSv4.1 Goals</name> | |||
<t> | ||||
NFSv4.1 has the following goals, within the framework | NFSv4.1 has the following goals, within the framework | |||
established by the overall NFSv4 goals. | established by the overall NFSv4 goals. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
To correct significant structural weaknesses and oversights | To correct significant structural weaknesses and oversights | |||
discovered in the base protocol. | discovered in the base protocol. | |||
</t> | </li> | |||
<t> | <li> | |||
To add clarity and specificity to areas left | To add clarity and specificity to areas left | |||
unaddressed or not addressed in sufficient | unaddressed or not addressed in sufficient | |||
detail in the base protocol. However, as stated | detail in the base protocol. However, as stated | |||
in <xref target="scope_of_doc" />, it is not | in <xref target="scope_of_doc" format="default"/>, it is not | |||
a goal to clarify the NFSv4.0 protocol in the | a goal to clarify the NFSv4.0 protocol in the | |||
NFSv4.1 specification. | NFSv4.1 specification. | |||
</t> | </li> | |||
<t> | <li> | |||
To add specific features based on experience with the existing | To add specific features based on experience with the existing | |||
protocol and recent industry developments. | protocol and recent industry developments. | |||
</t> | </li> | |||
<t> | <li> | |||
To provide protocol support to take advantage of clustered | To provide protocol support to take advantage of clustered | |||
server deployments including the ability to provide scalable | server deployments including the ability to provide scalable | |||
parallel access to files distributed among multiple servers. | parallel access to files distributed among multiple servers. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section anchor="intro_definitions" numbered="true" toc="default"> | |||
<section anchor="intro_definitions" title="General Definitions"> | <name>General Definitions</name> | |||
<t> | <t> | |||
The following definitions provide an appropriate context for the reader. | The following definitions provide an appropriate context for the reader. | |||
<list style='hanging'> | </t> | |||
<t hangText="Byte:" anchor="byte"> | <dl newline="false" spacing="normal"> | |||
<dt>Byte:</dt> | ||||
<dd anchor="byte"> | ||||
In this document, a byte is an octet, i.e., a datum | In this document, a byte is an octet, i.e., a datum | |||
exactly 8 bits in length. | exactly 8 bits in length. | |||
</t> | </dd> | |||
<t hangText="Client:" anchor="client_def"> | <dt>Client:</dt> | |||
<dd anchor="client_def"> | ||||
<t> | ||||
The client is the entity that accesses the NFS server's | The client is the entity that accesses the NFS server's | |||
resources. The client may be an application that contains | resources. The client may be an application that contains | |||
the logic to access the NFS server directly. The client | the logic to access the NFS server directly. The client | |||
may also be the traditional operating system client that | may also be the traditional operating system client that | |||
provides remote file system services for a set of applications. | provides remote file system services for a set of applications. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
A client is uniquely identified by a client owner. | A client is uniquely identified by a client owner. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
With reference to byte-range locking, the client is also the entity th at | With reference to byte-range locking, the client is also the entity th at | |||
maintains a set of locks on behalf of one or more | maintains a set of locks on behalf of one or more | |||
applications. This client is responsible for crash or | applications. This client is responsible for crash or | |||
failure recovery for those locks it manages. | failure recovery for those locks it manages. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
Note that multiple clients may share the same transport and | Note that multiple clients may share the same transport and | |||
connection and | connection and | |||
multiple clients may exist on the same network node. | multiple clients may exist on the same network node. | |||
</t> | </t> | |||
<t hangText="Client ID:"> | </dd> | |||
<dt>Client ID:</dt> | ||||
<dd> | ||||
The client ID is a 64-bit quantity used as a unique, short-hand refere nce to | The client ID is a 64-bit quantity used as a unique, short-hand refere nce to | |||
a client-supplied verifier and client owner. The server is | a client-supplied verifier and client owner. The server is | |||
responsible for supplying the client ID. | responsible for supplying the client ID. | |||
</t> | </dd> | |||
<t hangText="Client Owner:"> | <dt>Client Owner:</dt> | |||
<dd> | ||||
The client owner is a unique string, opaque to the server, | The client owner is a unique string, opaque to the server, | |||
that identifies a client. Multiple network connections and source | that identifies a client. Multiple network connections and source | |||
network addresses originating from those connections may share | network addresses originating from those connections may share | |||
a client owner. The server is expected to treat requests | a client owner. The server is expected to treat requests | |||
from connections with the same client owner as coming from | from connections with the same client owner as coming from | |||
the same client. | the same client. | |||
</t> | </dd> | |||
<dt>File System:</dt> | ||||
<t hangText="File System:"> | <dd> | |||
The file system is the collection of objects on a server (as | The file system is the collection of objects on a server (as | |||
identified by the major identifier of a server | identified by the major identifier of a server | |||
owner, which is defined later in this section) | owner, which is defined later in this section) | |||
that share the same fsid attribute (see <xref | that share the same fsid attribute (see <xref target="attrdef_fsid" fo | |||
target="attrdef_fsid"/>). | rmat="default"/>). | |||
</t> | </dd> | |||
<t hangText="Lease:"> | <dt>Lease:</dt> | |||
<dd> | ||||
<t> | ||||
A lease is an interval of time defined by the server for which the | A lease is an interval of time defined by the server for which the | |||
client is irrevocably granted locks. At the end of a | client is irrevocably granted locks. At the end of a | |||
lease period, locks may be revoked if the lease has not | lease period, locks may be revoked if the lease has not | |||
been extended. A lock must be revoked if a conflicting | been extended. A lock must be revoked if a conflicting | |||
lock has been granted after the lease interval. | lock has been granted after the lease interval. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
A server grants a client a single lease for all state. | A server grants a client a single lease for all state. | |||
</t> | </t> | |||
<t hangText="Lock:"> | </dd> | |||
<dt>Lock:</dt> | ||||
<dd> | ||||
The term "lock" is used to refer to byte-range (in UNIX environments, | The term "lock" is used to refer to byte-range (in UNIX environments, | |||
also known as record) | also known as record) | |||
locks, share reservations, delegations, or layouts unless | locks, share reservations, delegations, or layouts unless | |||
specifically stated otherwise. | specifically stated otherwise. | |||
</t> | </dd> | |||
<dt>Secret State Verifier (SSV):</dt> | ||||
<t hangText="Secret State Verifier (SSV):"> | <dd> | |||
The SSV is a unique secret key shared between a client and | The SSV is a unique secret key shared between a client and | |||
server. The SSV serves as the secret key for an internal (that | server. The SSV serves as the secret key for an internal (that | |||
is, internal to NFSv4.1) Generic Security Services (GSS) | is, internal to NFSv4.1) Generic Security Services (GSS) | |||
mechanism (the SSV GSS mechanism; | mechanism (the SSV GSS mechanism; | |||
see <xref target="ssv_mech"/>). The SSV GSS mechanism uses the | see <xref target="ssv_mech" format="default"/>). The SSV GSS mechanis m uses the | |||
SSV to compute message integrity code (MIC) and Wrap tokens. | SSV to compute message integrity code (MIC) and Wrap tokens. | |||
See <xref target="protect_state_change"/> for more details on how NFSv 4.1 uses | See <xref target="protect_state_change" format="default"/> for more de tails on how NFSv4.1 uses | |||
the SSV and the SSV GSS mechanism. | the SSV and the SSV GSS mechanism. | |||
</t> | </dd> | |||
<dt>Server:</dt> | ||||
<t hangText="Server:"> | <dd> | |||
The Server is the entity responsible for coordinating | The Server is the entity responsible for coordinating | |||
client access to a set of file systems and is identified by a server | client access to a set of file systems and is identified by a server | |||
owner. A server can span multiple network addresses. | owner. A server can span multiple network addresses. | |||
</t> | </dd> | |||
<t hangText="Server Owner:"> | <dt>Server Owner:</dt> | |||
<dd> | ||||
The server owner identifies the server to the client. | The server owner identifies the server to the client. | |||
The server owner consists of a major identifier and a minor identifier . | The server owner consists of a major identifier and a minor identifier . | |||
When the client has two connections each to a peer with the | When the client has two connections each to a peer with the | |||
same major identifier, the client assumes that both peers are | same major identifier, the client assumes that both peers are | |||
the same server (the server namespace is the | the same server (the server namespace is the | |||
same via each connection) and that | same via each connection) and that | |||
lock state is sharable across both connections. When each peer | lock state is shareable across both connections. When each peer | |||
has both the same major and minor identifiers, the client | has both the same major and minor identifiers, the client | |||
assumes that each connection might be associable with the same session . | assumes that each connection might be associable with the same session . | |||
</t> | </dd> | |||
<t hangText="Stable Storage:"> | <dt>Stable Storage:</dt> | |||
<dd> | ||||
<t> | ||||
Stable storage is storage from which data stored by | Stable storage is storage from which data stored by | |||
an NFSv4.1 server can be recovered without data | an NFSv4.1 server can be recovered without data | |||
loss from multiple power failures (including cascading | loss from multiple power failures (including cascading | |||
power failures, that is, several power failures in quick | power failures, that is, several power failures in quick | |||
succession), operating system failures, and/or hardware | succession), operating system failures, and/or hardware | |||
failure of components other than the storage medium itself | failure of components other than the storage medium itself | |||
(such as disk, nonvolatile RAM, flash memory, etc.). | (such as disk, nonvolatile RAM, flash memory, etc.). | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
Some examples of stable storage that are allowable for an | Some examples of stable storage that are allowable for an | |||
NFS server include: | NFS server include: | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
Media commit of data; that is, the modified data has | Media commit of data; that is, the modified data has | |||
been successfully written to the disk media, for | been successfully written to the disk media, for | |||
example, the disk platter. | example, the disk platter. | |||
</t> | </li> | |||
<t> | <li> | |||
An immediate reply disk drive with battery-backed, | An immediate reply disk drive with battery-backed, | |||
on-drive intermediate storage or uninterruptible power | on-drive intermediate storage or uninterruptible power | |||
system (UPS). | system (UPS). | |||
</t> | </li> | |||
<t> | <li> | |||
Server commit of data with battery-backed intermediate | Server commit of data with battery-backed intermediate | |||
storage and recovery software. | storage and recovery software. | |||
</t> | </li> | |||
<t> | <li> | |||
Cache commit with uninterruptible power system (UPS) and | Cache commit with uninterruptible power system (UPS) and | |||
recovery software. | recovery software. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | </dd> | |||
<t hangText="Stateid:"> | <dt>Stateid:</dt> | |||
<dd> | ||||
A stateid is a 128-bit quantity returned by a server that uniquely | A stateid is a 128-bit quantity returned by a server that uniquely | |||
defines the open and locking states provided by the server | defines the open and locking states provided by the server | |||
for a specific open-owner or lock-owner/open-owner pair | for a specific open-owner or lock-owner/open-owner pair | |||
for a specific file and type of lock. | for a specific file and type of lock. | |||
</t> | </dd> | |||
<t hangText="Verifier:"> | <dt>Verifier:</dt> | |||
<dd> | ||||
A verifier is a 64-bit quantity generated by the client that the serve r | A verifier is a 64-bit quantity generated by the client that the serve r | |||
can use to determine if the client has restarted and lost | can use to determine if the client has restarted and lost | |||
all previous lock state. | all previous lock state. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | </section> | |||
</section> | <section anchor="feature-overview" numbered="true" toc="default"> | |||
<section anchor="feature-overview" | <name>Overview of NFSv4.1 Features</name> | |||
title="Overview of NFSv4.1 Features"> | <t> | |||
<t> | ||||
The major features of | The major features of | |||
the NFSv4.1 protocol will be reviewed in brief. This will be done | the NFSv4.1 protocol will be reviewed in brief. This will be done | |||
to provide an appropriate context for both the reader who is familiar | to provide an appropriate context for both the reader who is familiar | |||
with the previous versions of the NFS protocol and the reader | with the previous versions of the NFS protocol and the reader | |||
who is new to the NFS protocols. For the reader new to the NFS protocols, | who is new to the NFS protocols. For the reader new to the NFS protocols, | |||
there is still a set of fundamental knowledge that is expected. | there is still a set of fundamental knowledge that is expected. | |||
The reader should be familiar with the External Data | The reader should be familiar with the External Data | |||
Representation (XDR) and Remote Procedure Call (RPC) protocols | Representation (XDR) and Remote Procedure Call (RPC) protocols | |||
as described in <xref target="RFC4506" /> and <xref target="RFC5531" />. | as described in <xref target="RFC4506" format="default"/> and <xref target ="RFC5531" format="default"/>. | |||
A basic knowledge of file systems and distributed file systems is expected as well. | A basic knowledge of file systems and distributed file systems is expected as well. | |||
</t> | </t> | |||
<t> | <t> | |||
In general, this specification of NFSv4.1 will | In general, this specification of NFSv4.1 will | |||
not distinguish those features added in minor version | not distinguish those features added in minor version | |||
1 from those present in the base protocol but | 1 from those present in the base protocol but | |||
will treat NFSv4.1 as a unified whole. See <xref | will treat NFSv4.1 as a unified whole. See <xref target="intro_difference | |||
target="intro_differences" /> for a summary of | s" format="default"/> for a summary of | |||
the differences between NFSv4.0 and NFSv4.1. | the differences between NFSv4.0 and NFSv4.1. | |||
</t> | </t> | |||
<section anchor="rpc_and_security" title="RPC and Security"> | <section anchor="rpc_and_security" numbered="true" toc="default"> | |||
<t> | <name>RPC and Security</name> | |||
<t> | ||||
As with previous versions of NFS, the External Data Representation | As with previous versions of NFS, the External Data Representation | |||
(XDR) and Remote Procedure Call (RPC) mechanisms used for the NFSv4.1 pr otocol are those defined in | (XDR) and Remote Procedure Call (RPC) mechanisms used for the NFSv4.1 pr otocol are those defined in | |||
<xref target="RFC4506" /> and <xref target="RFC5531" />. To | <xref target="RFC4506" format="default"/> and <xref target="RFC5531" for mat="default"/>. To | |||
meet end-to-end security requirements, the RPCSEC_GSS framework | meet end-to-end security requirements, the RPCSEC_GSS framework | |||
<xref target="RFC2203" /> is used to extend the basic | <xref target="RFC2203" format="default"/> is used to extend the basic | |||
RPC security. With the | RPC security. With the | |||
use of RPCSEC_GSS, various mechanisms can be provided to offer | use of RPCSEC_GSS, various mechanisms can be provided to offer | |||
authentication, integrity, and privacy to the NFSv4 protocol. | authentication, integrity, and privacy to the NFSv4 protocol. | |||
Kerberos V5 is used as described in | Kerberos V5 is used as described in | |||
<xref target="RFC4121" /> to provide one | <xref target="RFC4121" format="default"/> to provide one | |||
security framework. | security framework. | |||
With the use of | With the use of | |||
RPCSEC_GSS, other mechanisms may also be specified and used for NFSv4.1 security. | RPCSEC_GSS, other mechanisms may also be specified and used for NFSv4.1 security. | |||
</t> | </t> | |||
<t> | <t> | |||
To enable in-band security negotiation, the NFSv4.1 protocol | To enable in-band security negotiation, the NFSv4.1 protocol | |||
has operations that provide the client a method of | has operations that provide the client a method of | |||
querying the server about its policies regarding which security | querying the server about its policies regarding which security | |||
mechanisms must be used for access to the server's file system | mechanisms must be used for access to the server's file system | |||
resources. With this, the client can securely match the security | resources. With this, the client can securely match the security | |||
mechanism that meets the policies specified at both the client and | mechanism that meets the policies specified at both the client and | |||
server. | server. | |||
</t> | </t> | |||
<t> | <t> | |||
NFSv4.1 introduces parallel access (see <xref | NFSv4.1 introduces parallel access (see <xref target="parallel_access" fo | |||
target="parallel_access"/>), which is | rmat="default"/>), which is | |||
called pNFS. | called pNFS. | |||
The security framework | The security framework | |||
described in this section is | described in this section is | |||
significantly modified by the | significantly modified by the | |||
introduction of pNFS (see <xref | introduction of pNFS (see <xref target="security_considerations_pnfs" for | |||
target="security_considerations_pnfs"/>), | mat="default"/>), | |||
because data access is sometimes not over | because data access is sometimes not over | |||
RPC. The level of significance varies | RPC. The level of significance varies | |||
with the storage protocol (see <xref | with the storage protocol (see <xref target="storage_protocol" format="de | |||
target="storage_protocol"/>) and can be as low as zero | fault"/>) and can be as low as zero | |||
impact (see <xref target="file_security_considerations"/>). | impact (see <xref target="file_security_considerations" format="default" | |||
/>). | ||||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="protocol_structure" | <section anchor="protocol_structure" numbered="true" toc="default"> | |||
title="Protocol Structure"> | <name>Protocol Structure</name> | |||
<section anchor="core_protocol" | <section anchor="core_protocol" numbered="true" toc="default"> | |||
title="Core Protocol"> | <name>Core Protocol</name> | |||
<t> | <t> | |||
Unlike NFSv3, which used a series of ancillary | Unlike NFSv3, which used a series of ancillary | |||
protocols (e.g., NLM, NSM (Network Status Monitor), MOUNT), within all minor versions | protocols (e.g., NLM, NSM (Network Status Monitor), MOUNT), within all minor versions | |||
of NFSv4 a single RPC protocol is used to make requests to | of NFSv4 a single RPC protocol is used to make requests to | |||
the server. | the server. | |||
Facilities that had been separate protocols, such | Facilities that had been separate protocols, such | |||
as locking, are now integrated within a single unified | as locking, are now integrated within a single unified | |||
protocol. | protocol. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="parallel_access" | <section anchor="parallel_access" numbered="true" toc="default"> | |||
title="Parallel Access"> | <name>Parallel Access</name> | |||
<t> | <t> | |||
Minor version 1 supports high-performance data access to a | Minor version 1 supports high-performance data access to a | |||
clustered server implementation by enabling a separation of | clustered server implementation by enabling a separation of | |||
metadata access and data access, with the latter done to | metadata access and data access, with the latter done to | |||
multiple servers in parallel. | multiple servers in parallel. | |||
</t> | </t> | |||
<t> | <t> | |||
Such parallel data access is controlled by recallable | Such parallel data access is controlled by recallable | |||
objects known as "layouts", which are integrated into the | objects known as "layouts", which are integrated into the | |||
protocol locking model. Clients direct requests for | protocol locking model. Clients direct requests for | |||
data access to a set of data servers specified by the | data access to a set of data servers specified by the | |||
layout via a data | layout via a data | |||
storage protocol which may be NFSv4.1 or may be another | storage protocol which may be NFSv4.1 or may be another | |||
protocol. | protocol. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
Because the protocols used for parallel | Because the protocols used for parallel | |||
data access are not necessarily | data access are not necessarily | |||
RPC-based, the RPC-based security model | RPC-based, the RPC-based security model | |||
(<xref target="rpc_and_security"/>) is | (<xref target="rpc_and_security" format="default"/>) is | |||
obviously impacted (see <xref | obviously impacted (see <xref target="security_considerations_pnfs" for | |||
target="security_considerations_pnfs"/>). | mat="default"/>). | |||
The degree of impact varies with the | The degree of impact varies with the | |||
storage protocol (see <xref | storage protocol (see <xref target="storage_protocol" format="default"/ | |||
target="storage_protocol"/>) used for | >) used for | |||
data access, and can be as low as zero (see | data access, and can be as low as zero (see | |||
<xref target="file_security_considerations"/>). | <xref target="file_security_considerations" format="default"/>). | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="file_system_model" title="File System Model"> | <section anchor="file_system_model" numbered="true" toc="default"> | |||
<t> | <name>File System Model</name> | |||
<t> | ||||
The general file system | The general file system | |||
model used for the NFSv4.1 protocol | model used for the NFSv4.1 protocol | |||
is the same as previous versions. The server file system is | is the same as previous versions. The server file system is | |||
hierarchical with the regular files contained within being | hierarchical with the regular files contained within being | |||
treated as opaque byte | treated as opaque byte | |||
streams. In a slight departure, file and directory names are encoded | streams. In a slight departure, file and directory names are encoded | |||
with UTF-8 to deal with the basics of internationalization. | with UTF-8 to deal with the basics of internationalization. | |||
</t> | </t> | |||
<t> | <t> | |||
The NFSv4.1 protocol does not require a separate | The NFSv4.1 protocol does not require a separate | |||
protocol to provide for the initial mapping between path | protocol to provide for the initial mapping between path | |||
name and filehandle. All file systems exported by a server | name and filehandle. All file systems exported by a server | |||
are presented as a tree so that all file systems are reachable | are presented as a tree so that all file systems are reachable | |||
from a special per-server global root filehandle. This | from a special per-server global root filehandle. This | |||
allows LOOKUP operations to be used to perform functions | allows LOOKUP operations to be used to perform functions | |||
previously provided by the MOUNT protocol. The server | previously provided by the MOUNT protocol. The server | |||
provides any necessary pseudo file systems to bridge any | provides any necessary pseudo file systems to bridge any | |||
gaps that arise due to unexported gaps between exported | gaps that arise due to unexported gaps between exported | |||
file systems. | file systems. | |||
</t> | </t> | |||
<section anchor="intro_filehandles" title="Filehandles"> | <section anchor="intro_filehandles" numbered="true" toc="default"> | |||
<t> | <name>Filehandles</name> | |||
<t> | ||||
As in previous versions of the NFS protocol, opaque | As in previous versions of the NFS protocol, opaque | |||
filehandles are used to identify individual files | filehandles are used to identify individual files | |||
and directories. Lookup-type and create operations | and directories. Lookup-type and create operations | |||
translate file and directory names to | translate file and directory names to | |||
filehandles, which are then used to identify objects | filehandles, which are then used to identify objects | |||
in subsequent operations. | in subsequent operations. | |||
</t> | </t> | |||
<t> | <t> | |||
The NFSv4.1 protocol provides support for | The NFSv4.1 protocol provides support for | |||
persistent filehandles, guaranteed to be valid | persistent filehandles, guaranteed to be valid | |||
for the lifetime of the file system object designated. | for the lifetime of the file system object designated. | |||
In addition, it provides support to servers to provide | In addition, it provides support to servers to provide | |||
filehandles with more limited validity guarantees, | filehandles with more limited validity guarantees, | |||
called volatile filehandles. | called volatile filehandles. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="intro_attributes" title="File Attributes"> | <section anchor="intro_attributes" numbered="true" toc="default"> | |||
<t> | <name>File Attributes</name> | |||
<t> | ||||
The NFSv4.1 protocol has a rich and extensible | The NFSv4.1 protocol has a rich and extensible | |||
file object attribute structure, which is divided | file object attribute structure, which is divided | |||
into REQUIRED, RECOMMENDED, and named attributes | into <bcp14>REQUIRED</bcp14>, <bcp14>RECOMMENDED</bcp14>, and named att | |||
(see <xref target="file_attributes"/>). | ributes | |||
(see <xref target="file_attributes" format="default"/>). | ||||
</t> | </t> | |||
<t> | <t> | |||
Several (but not all) of the REQUIRED attributes | Several (but not all) of the <bcp14>REQUIRED</bcp14> attributes | |||
are derived from the attributes of NFSv3 (see | are derived from the attributes of NFSv3 (see | |||
the definition of the fattr3 data type in <xref | the definition of the fattr3 data type in <xref target="RFC1813" format | |||
target="RFC1813"/>). An example of a REQUIRED | ="default"/>). An example of a <bcp14>REQUIRED</bcp14> | |||
attribute is the file object's type (<xref | attribute is the file object's type (<xref target="attrdef_type" format | |||
target="attrdef_type"/>) so that regular files | ="default"/>) so that regular files | |||
can be distinguished from directories (also known | can be distinguished from directories (also known | |||
as folders in some operating environments) and | as folders in some operating environments) and | |||
other types of objects. REQUIRED attributes are | other types of objects. <bcp14>REQUIRED</bcp14> attributes are | |||
discussed in <xref | discussed in <xref target="mandatory_attributes_intro" format="default" | |||
target="mandatory_attributes_intro"/>. | />. | |||
</t> | ||||
<t> | </t> | |||
An example of three RECOMMENDED attributes are | <t> | |||
An example of three <bcp14>RECOMMENDED</bcp14> attributes are | ||||
acl, sacl, and dacl. These attributes define an | acl, sacl, and dacl. These attributes define an | |||
Access Control List (ACL) on a file object | Access Control List (ACL) on a file object | |||
(<xref target="acl"/>). An ACL provides | (<xref target="acl" format="default"/>). An ACL provides | |||
directory and file access control beyond the | directory and file access control beyond the | |||
model used in NFSv3. The ACL definition allows | model used in NFSv3. The ACL definition allows | |||
for specification of specific sets of permissions | for specification of specific sets of permissions | |||
for individual users and groups. In addition, | for individual users and groups. In addition, | |||
ACL inheritance allows propagation of access | ACL inheritance allows propagation of access | |||
permissions and restrictions down a directory tree | permissions and restrictions down a directory tree | |||
as file system objects are created. RECOMMENDED | as file system objects are created. <bcp14>RECOMMENDED</bcp14> | |||
attributes are discussed in <xref | attributes are discussed in <xref target="recommended_attributes_intro" | |||
target="recommended_attributes_intro"/>. | format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
A named attribute is an opaque byte stream that is associated | A named attribute is an opaque byte stream that is associated | |||
with a directory or file and referred to by a string name. | with a directory or file and referred to by a string name. | |||
Named attributes are meant to be used by client applications | Named attributes are meant to be used by client applications | |||
as a method to associate application-specific data with a | as a method to associate application-specific data with a | |||
regular file or directory. NFSv4.1 modifies named attributes | regular file or directory. NFSv4.1 modifies named attributes | |||
relative to NFSv4.0 by tightening the allowed operations in | relative to NFSv4.0 by tightening the allowed operations in | |||
order to prevent the development of non-interoperable | order to prevent the development of non-interoperable | |||
implementations. Named attributes are discussed in <xref target="name d_attributes_intro" />. | implementations. Named attributes are discussed in <xref target="name d_attributes_intro" format="default"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Multi-Server Namespace" | <section anchor="PREP-intro" numbered="true" toc="default"> | |||
anchor="PREP-intro"> | <name>Multi-Server Namespace</name> | |||
<t> | <t> | |||
NFSv4.1 contains a number of features to allow | NFSv4.1 contains a number of features to allow | |||
implementation of namespaces that cross server boundaries | implementation of namespaces that cross server boundaries | |||
and that allow and facilitate a non-disruptive transfer of | and that allow and facilitate a nondisruptive transfer of | |||
support for individual file systems between servers. They | support for individual file systems between servers. They | |||
are all based upon attributes that allow one file system to | are all based upon attributes that allow one file system to | |||
specify alternate, additional, and new location information | specify alternate, additional, and new location information | |||
that specifies how the client may access | that specifies how the client may access | |||
that file system. | that file system. | |||
</t> | </t> | |||
<t> | <t> | |||
These attributes can be used to provide for individual active | These attributes can be used to provide for individual active | |||
file systems: | file systems: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Alternate network addresses to access the | Alternate network addresses to access the | |||
current file system instance. | current file system instance. | |||
</t> | </li> | |||
<t> | <li> | |||
The locations of alternate file system instances | The locations of alternate file system instances | |||
or replicas to be used in the event that the current | or replicas to be used in the event that the current | |||
file system instance becomes unavailable. | file system instance becomes unavailable. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
These file system location | These file system location | |||
attributes may be used together with the concept | attributes may be used together with the concept | |||
of absent file systems, in which a position in the server | of absent file systems, in which a position in the server | |||
namespace is associated with locations on other servers without | namespace is associated with locations on other servers without | |||
there being any corresponding file system instance on the | there being any corresponding file system instance on the | |||
current server. For example, | current server. For example, | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
These attributes may be used with absent file systems | These attributes may be used with absent file systems | |||
to implement referrals whereby one server may direct the | to implement referrals whereby one server may direct the | |||
client to a file system provided by another server. This | client to a file system provided by another server. This | |||
allows extensive multi-server namespaces to be constructed. | allows extensive multi-server namespaces to be constructed. | |||
</t> | </li> | |||
<t> | <li> | |||
These attributes may be provided when a previously | These attributes may be provided when a previously | |||
present file system becomes absent. This allows | present file system becomes absent. This allows | |||
non-disruptive migration of file systems to alternate | nondisruptive migration of file systems to alternate | |||
servers. | servers. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="intro_locking" numbered="true" toc="default"> | |||
<section anchor="intro_locking" title="Locking Facilities"> | <name>Locking Facilities</name> | |||
<t> | <t> | |||
As mentioned previously, NFSv4.1 is a single protocol that | As mentioned previously, NFSv4.1 is a single protocol that | |||
includes locking facilities. These locking facilities | includes locking facilities. These locking facilities | |||
include support for many types of locks including a number | include support for many types of locks including a number | |||
of sorts of recallable locks. Recallable locks such as | of sorts of recallable locks. Recallable locks such as | |||
delegations allow the client to be assured that certain | delegations allow the client to be assured that certain | |||
events will not occur so long as that lock is held. When | events will not occur so long as that lock is held. When | |||
circumstances change, the lock is recalled | circumstances change, the lock is recalled | |||
via a callback request. The assurances provided by | via a callback request. The assurances provided by | |||
delegations allow more extensive caching to be done safely | delegations allow more extensive caching to be done safely | |||
when circumstances allow it. | when circumstances allow it. | |||
</t> | ||||
<t> | ||||
The types of locks are: | ||||
</t> | ||||
<t> | ||||
<list style="symbols"> | ||||
<t> | ||||
Share reservations as established by OPEN operations. | ||||
</t> | </t> | |||
<t> | <t> | |||
Byte-range locks. | The types of locks are: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Share reservations as established by OPEN operations. | ||||
</li> | ||||
<li> | ||||
Byte-range locks. | ||||
</li> | ||||
<li> | ||||
File delegations, which are recallable locks that assure | File delegations, which are recallable locks that assure | |||
the holder that inconsistent opens and file changes cannot | the holder that inconsistent opens and file changes cannot | |||
occur so long as the delegation is held. | occur so long as the delegation is held. | |||
</t> | </li> | |||
<t> | <li> | |||
Directory delegations, which are recallable locks | Directory delegations, which are recallable locks | |||
that assure the holder that inconsistent directory | that assure the holder that inconsistent directory | |||
modifications cannot occur so long as the delegation | modifications cannot occur so long as the delegation | |||
is held. | is held. | |||
</t> | </li> | |||
<t> | <li> | |||
Layouts, which are recallable objects that assure the | Layouts, which are recallable objects that assure the | |||
holder that direct access to the file data may be | holder that direct access to the file data may be | |||
performed directly by the client and that no change | performed directly by the client and that no change | |||
to the data's location that is inconsistent with that access | to the data's location that is inconsistent with that access | |||
may be made so long as the layout is held. | may be made so long as the layout is held. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
All locks for a given client are tied together under a | All locks for a given client are tied together under a | |||
single client-wide lease. All requests made on sessions | single client-wide lease. All requests made on sessions | |||
associated with the client renew that lease. When the client's | associated with the client renew that lease. When the client's | |||
lease | lease | |||
is not promptly renewed, the client's locks are subject to revocation. | is not promptly renewed, the client's locks are subject to revocation. | |||
In the event of server restart, clients have the | In the event of server restart, clients have the | |||
opportunity to safely reclaim their locks within a special | opportunity to safely reclaim their locks within a special | |||
grace period. | grace period. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="intro_differences" title="Differences from NFSv4.0"> | <section anchor="intro_differences" numbered="true" toc="default"> | |||
<t> | <name>Differences from NFSv4.0</name> | |||
<t> | ||||
The following summarizes the major differences between minor version | The following summarizes the major differences between minor version | |||
1 and the base protocol: | 1 and the base protocol: | |||
<list style="symbols"> | ||||
<t> | ||||
Implementation of the sessions model (<xref target="Session"/>). | ||||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
Parallel access to data (<xref target="pnfs"/>). | <li> | |||
</t> | Implementation of the sessions model (<xref target="Session" format="d | |||
<t> | efault"/>). | |||
</li> | ||||
<li> | ||||
Parallel access to data (<xref target="pnfs" format="default"/>). | ||||
</li> | ||||
<li> | ||||
Addition of the RECLAIM_COMPLETE operation to better structure | Addition of the RECLAIM_COMPLETE operation to better structure | |||
the lock reclamation process (<xref target="OP_RECLAIM_COMPLETE"/>). | the lock reclamation process (<xref target="OP_RECLAIM_COMPLETE" forma | |||
</t> | t="default"/>). | |||
</li> | ||||
<t> | <li> | |||
<t> | ||||
Enhanced delegation support as follows. | Enhanced delegation support as follows. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Delegations on directories and other | Delegations on directories and other | |||
file types in addition to regular files (<xref | file types in addition to regular files (<xref target="OP_GET_DIR_DELE | |||
target="OP_GET_DIR_DELEGATION"/>, <xref | GATION" format="default"/>, <xref target="OP_WANT_DELEGATION" format="default"/> | |||
target="OP_WANT_DELEGATION"/>). | ). | |||
</t> | </li> | |||
<t> | <li> | |||
Operations to optimize acquisition of recalled | Operations to optimize acquisition of recalled | |||
or denied delegations (<xref | or denied delegations (<xref target="OP_WANT_DELEGATION" format="defau | |||
target="OP_WANT_DELEGATION"/>, <xref | lt"/>, <xref target="OP_CB_PUSH_DELEG" format="default"/>, <xref target="OP_CB_R | |||
target="OP_CB_PUSH_DELEG"/>, <xref | ECALLABLE_OBJ_AVAIL" format="default"/>). | |||
target="OP_CB_RECALLABLE_OBJ_AVAIL"/>). | ||||
</t> | ||||
<t> | </li> | |||
<li> | ||||
Notifications of changes to files and directories | Notifications of changes to files and directories | |||
(<xref target="OP_GET_DIR_DELEGATION"/>, <xref | (<xref target="OP_GET_DIR_DELEGATION" format="default"/>, <xref target | |||
target="OP_CB_NOTIFY"/>). | ="OP_CB_NOTIFY" format="default"/>). | |||
</t> | ||||
<t> | </li> | |||
<li> | ||||
A method to allow a server to indicate that it is | A method to allow a server to indicate that it is | |||
recalling one or more delegations for resource | recalling one or more delegations for resource | |||
management reasons, and thus a method to allow | management reasons, and thus a method to allow | |||
the client to pick which delegations to return | the client to pick which delegations to return | |||
(<xref target="OP_CB_RECALL_ANY"/>). | (<xref target="OP_CB_RECALL_ANY" format="default"/>). | |||
</t> | ||||
</list> | ||||
</t> | ||||
<t> | </li> | |||
</ul> | ||||
</li> | ||||
<li> | ||||
Attributes can be set atomically | Attributes can be set atomically | |||
during exclusive file create via the OPEN operation | during exclusive file create via the OPEN operation | |||
(see the new EXCLUSIVE4_1 creation method in | (see the new EXCLUSIVE4_1 creation method in | |||
<xref target="OP_OPEN"/>). | <xref target="OP_OPEN" format="default"/>). | |||
</t> | </li> | |||
<t> | <li> | |||
Open files can be preserved if removed and the | Open files can be preserved if removed and the | |||
hard link count ("hard link" is defined in | hard link count ("hard link" is defined in | |||
an <xref target="hardlink">Open Group</xref> standard) goes | an <xref target="hardlink" format="default">Open Group</xref> standard) goes | |||
to zero, thus obviating the | to zero, thus obviating the | |||
need for clients to rename deleted files to | need for clients to rename deleted files to | |||
partially hidden names -- colloquially called | partially hidden names -- colloquially called | |||
"silly rename" (see the new | "silly rename" (see the new | |||
OPEN4_RESULT_PRESERVE_UNLINKED reply flag in | OPEN4_RESULT_PRESERVE_UNLINKED reply flag in | |||
<xref target="OP_OPEN"/>). | <xref target="OP_OPEN" format="default"/>). | |||
</t> | </li> | |||
<t> | <li> | |||
Improved compatibility with Microsoft Windows for | Improved compatibility with Microsoft Windows for | |||
Access Control Lists (<xref | Access Control Lists (<xref target="attrdef_sacl" format="default"/>, < | |||
target="attrdef_sacl"/>, <xref | xref target="attrdef_dacl" format="default"/>, <xref target="auto_inherit" forma | |||
target="attrdef_dacl"/>, <xref | t="default"/>). | |||
target="auto_inherit"/>). | ||||
</t> | </li> | |||
<t> | <li> | |||
Data retention (<xref target="retention"/>). | Data retention (<xref target="retention" format="default"/>). | |||
</t> | </li> | |||
<t> | <li> | |||
Identification of the implementation of the NFS client | Identification of the implementation of the NFS client | |||
and server (<xref target="OP_EXCHANGE_ID"/>). | and server (<xref target="OP_EXCHANGE_ID" format="default"/>). | |||
</t> | ||||
<t> | </li> | |||
<li> | ||||
Support for notification of the availability of | Support for notification of the availability of | |||
byte-range locks (see the new | byte-range locks (see the new | |||
OPEN4_RESULT_MAY_NOTIFY_LOCK reply flag in <xref | OPEN4_RESULT_MAY_NOTIFY_LOCK reply flag in <xref target="OP_OPEN" forma | |||
target="OP_OPEN"/> and see <xref | t="default"/> and see <xref target="OP_CB_NOTIFY_LOCK" format="default"/>). | |||
target="OP_CB_NOTIFY_LOCK"/>). | ||||
</t> | ||||
<t> | </li> | |||
<li> | ||||
In NFSv4.1, LIPKEY and SPKM-3 are not required security mechanisms | In NFSv4.1, LIPKEY and SPKM-3 are not required security mechanisms | |||
<xref target="RFC2847"/>. | <xref target="RFC2847" format="default"/>. | |||
</t> | </li> | |||
</ul> | ||||
</list> | </section> | |||
</t> | </section> | |||
</section> | <section anchor="Core_Infrastructure" numbered="true" toc="default"> | |||
</section> | <name>Core Infrastructure</name> | |||
<section anchor="Introduction" numbered="true" toc="default"> | ||||
<section anchor="Core_Infrastructure" title="Core Infrastructure"> | <name>Introduction</name> | |||
<t> | ||||
<section anchor="Introduction" title="Introduction"> | ||||
<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> <!-- Introduction --> | </section> | |||
<section anchor="RPC_and_XDR" title="RPC and XDR"> | <section anchor="RPC_and_XDR" numbered="true" toc="default"> | |||
<t> | <name>RPC and XDR</name> | |||
<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"/> and | <xref target="RFC5531" format="default"/> and | |||
<xref target="RFC4506"/>. | <xref target="RFC4506" format="default"/>. | |||
</t> | </t> | |||
<section anchor="RPC-based_Security" numbered="true" toc="default"> | ||||
<section anchor="RPC-based_Security" title="RPC-Based Security"> | <name>RPC-Based Security</name> | |||
<t> | <t> | |||
Previous NFS versions have been thought of as having a | Previous NFS versions have been thought of as having a | |||
host-based authentication model, where the NFS server | host-based authentication model, where the NFS server | |||
authenticates the NFS client, and trusts the client | authenticates the NFS client, and trusts the client | |||
to authenticate all users. | to authenticate all users. | |||
Actually, NFS has always depended on RPC for | Actually, NFS has always depended on RPC for | |||
authentication. One of the first forms of RPC authentication, | authentication. One of the first forms of RPC authentication, | |||
AUTH_SYS, had no strong authentication and | AUTH_SYS, had no strong authentication and | |||
required a host-based authentication | required a host-based authentication | |||
approach. NFSv4.1 also depends on RPC for basic security | approach. NFSv4.1 also depends on RPC for basic security | |||
services and mandates RPC support for a user-based | services and mandates RPC support for a user-based | |||
authentication model. The user-based authentication | authentication model. The user-based authentication | |||
model has user principals authenticated by a server, and | model has user principals authenticated by a server, and | |||
in turn the server authenticated by user principals. | in turn the server authenticated by user principals. | |||
RPC provides some basic security services that are used | RPC provides some basic security services that are used | |||
by NFSv4.1. | by NFSv4.1. | |||
</t> | </t> | |||
<section anchor="RPC_Security_Flavors" numbered="true" toc="default"> | ||||
<section anchor="RPC_Security_Flavors" title="RPC Security Flavors"> | <name>RPC Security Flavors</name> | |||
<t> | <t> | |||
As described in Section 7.2 ("Authentication") of <xref target="RFC5531"/>, | As described in "Authentication", <xref target="RFC5531" sectionFormat="of" | |||
section="7"/>, | ||||
RPC security is encapsulated in the RPC header, via a | RPC security is encapsulated in the RPC header, via a | |||
security or authentication flavor, and information | security or authentication flavor, and information | |||
specific to the specified security flavor. | specific to the specified security flavor. | |||
Every RPC header conveys information used to identify | Every RPC header conveys information used to identify | |||
and authenticate a client and server. As discussed in | and authenticate a client and server. As discussed in | |||
<xref target="RPCSEC_GSS_and_Security_Services" />, | <xref target="RPCSEC_GSS_and_Security_Services" format="default"/>, | |||
some security flavors provide additional security | some security flavors provide additional security | |||
services. | services. | |||
</t> | </t> | |||
<t> | <t> | |||
NFSv4.1 clients and servers MUST implement RPCSEC_GSS. | NFSv4.1 clients and servers <bcp14>MUST</bcp14> implement RPCSEC_GSS. | |||
(This requirement to implement is not a requirement to | (This requirement to implement is not a requirement to | |||
use.) Other flavors, such as AUTH_NONE and | use.) Other flavors, such as AUTH_NONE and | |||
AUTH_SYS, MAY be implemented as well. | AUTH_SYS, <bcp14>MAY</bcp14> be implemented as well. | |||
</t> | </t> | |||
<section anchor="RPCSEC_GSS_and_Security_Services" numbered="true" t | ||||
<section anchor="RPCSEC_GSS_and_Security_Services" title="RPCSEC_GSS and Sec | oc="default"> | |||
urity Services"> | <name>RPCSEC_GSS and Security Services</name> | |||
<t> | <t> | |||
RPCSEC_GSS <xref target="RFC2203" /> uses the | RPCSEC_GSS <xref target="RFC2203" format="default"/> uses the | |||
functionality of GSS-API <xref target="RFC2743"/>. This allows for the | functionality of GSS-API <xref target="RFC2743" format="default"/>. This | |||
allows for the | ||||
use of various security mechanisms by the RPC layer | use of various security mechanisms by the RPC layer | |||
without the additional implementation overhead of | without the additional implementation overhead of | |||
adding RPC security flavors. | adding RPC security flavors. | |||
</t> | </t> | |||
<section anchor="Authentication_Integrity_Privacy" numbered="true" | ||||
<section anchor="Authentication_Integrity_Privacy" title="Identification, A | toc="default"> | |||
uthentication, Integrity, Privacy"> | <name>Identification, Authentication, Integrity, Privacy</name> | |||
<t> | <t> | |||
Via the GSS-API, RPCSEC_GSS can be used to identify and authenticate | Via the GSS-API, RPCSEC_GSS can be used to identify and authenticate | |||
users on clients to servers, and servers to users. It can also | users on clients to servers, and servers to users. It can also | |||
perform integrity checking on the entire RPC message, including | perform integrity checking on the entire RPC message, including | |||
the RPC header, and on the arguments or results. Finally, privacy, | the RPC header, and on the arguments or results. Finally, privacy, | |||
usually via encryption, is a service available with RPCSEC_GSS. | usually via encryption, is a service available with RPCSEC_GSS. | |||
Privacy is performed on the arguments and results. Note that | Privacy is performed on the arguments and results. Note that | |||
if privacy is selected, integrity, authentication, and identification | if privacy is selected, integrity, authentication, and identification | |||
are enabled. | are enabled. | |||
If privacy is not selected, but integrity is selected, authentication | If privacy is not selected, but integrity is selected, authentication | |||
and identification are enabled. If integrity and privacy are not | and identification are enabled. If integrity and privacy are not | |||
selected, but authentication is enabled, | selected, but authentication is enabled, | |||
identification is enabled. RPCSEC_GSS does not provide identification as | identification is enabled. RPCSEC_GSS does not provide identification as | |||
a separate service. | a separate service. | |||
</t> | </t> | |||
<t> | <t> | |||
Although GSS-API has an authentication service distinct from its | Although GSS-API has an authentication service distinct from its | |||
privacy and integrity services, GSS-API's | privacy and integrity services, GSS-API's | |||
authentication service is not used for RPCSEC_GSS's authentication | authentication service is not used for RPCSEC_GSS's authentication | |||
service. Instead, each RPC request and response header is | service. Instead, each RPC request and response header is | |||
integrity protected with the GSS-API integrity service, and | integrity protected with the GSS-API integrity service, and | |||
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" /> for more information. | identity. See <xref target="RFC2203" format="default"/> for more informati | |||
</t> | on. | |||
<t> | </t> | |||
NFSv4.1 client and servers MUST support RPCSEC_GSS's integrity and authent | <t> | |||
ication | NFSv4.1 client and servers <bcp14>MUST</bcp14> support RPCSEC_GSS's integr | |||
service. NFSv4.1 servers MUST support RPCSEC_GSS's privacy service. | ity and authentication | |||
NFSv4.1 clients SHOULD 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 servic | ||||
e. | ||||
</t> | </t> | |||
</section> <!-- Identity, Authentication, Integrity, Privacy --> | </section> | |||
<section anchor="security_mechs" title="Security Mechanisms for NFSv4.1"> | <section anchor="security_mechs" numbered="true" toc="default"> | |||
<t> | <name>Security Mechanisms for NFSv4.1</name> | |||
<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 | |||
MUST 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, | |||
quality of protection (QOP), and service (authentication, | quality of protection (QOP), and service (authentication, | |||
integrity, privacy). For the mandated security mechanisms, | integrity, privacy). For the mandated security mechanisms, | |||
NFSv4.1 specifies that a QOP of zero is used, leaving it up | NFSv4.1 specifies that a QOP of zero is used, leaving it up | |||
to the mechanism or the mechanism's configuration to map | to the mechanism or the mechanism's configuration to map | |||
QOP zero to | QOP zero to | |||
an appropriate level of protection. | an appropriate level of protection. | |||
Each mandated mechanism specifies a minimum set of cryptographic | Each mandated mechanism specifies a minimum set of cryptographic | |||
algorithms for implementing integrity and privacy. NFSv4.1 | algorithms for implementing integrity and privacy. NFSv4.1 | |||
clients and servers MUST be implemented on operating environments | clients and servers <bcp14>MUST</bcp14> be implemented on operating enviro | |||
that comply with the REQUIRED cryptographic algorithms | nments | |||
of each REQUIRED mechanism. | that comply with the <bcp14>REQUIRED</bcp14> cryptographic algorithms | |||
</t> | of each <bcp14>REQUIRED</bcp14> mechanism. | |||
</t> | ||||
<section anchor="kerberosv5" title="Kerberos V5"> | <section anchor="kerberosv5" numbered="true" toc="default"> | |||
<t> | <name>Kerberos V5</name> | |||
<t> | ||||
The Kerberos V5 GSS-API mechanism as described in | The Kerberos V5 GSS-API mechanism as described in | |||
<xref target="RFC4121"/> MUST be implemented with | <xref target="RFC4121" format="default"/> <bcp14>MUST</bcp14> be implemen ted with | |||
the RPCSEC_GSS services as specified in the following | the RPCSEC_GSS services as specified in the following | |||
table: | table: | |||
</t> | </t> | |||
<t> | <artwork name="" type="" align="left" alt=""><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
column descriptions: | column descriptions: | |||
1 == number of pseudo flavor | 1 == number of pseudo flavor | |||
2 == name of pseudo flavor | 2 == name of pseudo flavor | |||
3 == mechanism's OID | 3 == mechanism's OID | |||
4 == RPCSEC_GSS service | 4 == RPCSEC_GSS service | |||
5 == NFSv4.1 clients MUST support | 5 == NFSv4.1 clients MUST support | |||
6 == NFSv4.1 servers MUST support | 6 == NFSv4.1 servers MUST support | |||
1 2 3 4 5 6 | 1 2 3 4 5 6 | |||
------------------------------------------------------------------ | ------------------------------------------------------------------ | |||
390003 krb5 1.2.840.113554.1.2.2 rpc_gss_svc_none yes yes | 390003 krb5 1.2.840.113554.1.2.2 rpc_gss_svc_none yes yes | |||
390004 krb5i 1.2.840.113554.1.2.2 rpc_gss_svc_integrity yes yes | 390004 krb5i 1.2.840.113554.1.2.2 rpc_gss_svc_integrity yes yes | |||
390005 krb5p 1.2.840.113554.1.2.2 rpc_gss_svc_privacy no yes | 390005 krb5p 1.2.840.113554.1.2.2 rpc_gss_svc_privacy no yes | |||
</artwork> | ]]></artwork> | |||
</figure> | <t> | |||
</t> | ||||
<t> | ||||
Note that the number and name of the pseudo flavor | Note that the number and name of the pseudo flavor | |||
are presented here as a mapping aid to the implementor. | are presented here as a mapping aid to the implementor. | |||
Because the NFSv4.1 protocol includes a method to negotiate | Because the NFSv4.1 protocol includes a method to negotiate | |||
security and it understands the GSS-API mechanism, the pseudo flavor | security and it understands the GSS-API mechanism, the pseudo flavor | |||
is not needed. The pseudo flavor is needed for the NFSv3 since the secur ity negotiation is done via | is not needed. The pseudo flavor is needed for the NFSv3 since the secur ity negotiation is done via | |||
the MOUNT protocol as described in <xref target="RFC2623"/>. | the MOUNT protocol as described in <xref target="RFC2623" format="default | |||
</t> | "/>. | |||
<t> | </t> | |||
<t> | ||||
At the time NFSv4.1 was specified, the Advanced Encryption | At the time NFSv4.1 was specified, the Advanced Encryption | |||
Standard (AES) with HMAC-SHA1 was | Standard (AES) with HMAC-SHA1 was | |||
a REQUIRED algorithm set for Kerberos V5. In contrast, when | a <bcp14>REQUIRED</bcp14> algorithm set for Kerberos V5. In contrast, whe | |||
NFSv4.0 was specified, weaker algorithm sets were REQUIRED for | n | |||
Kerberos V5, and were REQUIRED in the NFSv4.0 specification, because | NFSv4.0 was specified, weaker algorithm sets were <bcp14>REQUIRED</bcp14> | |||
for | ||||
Kerberos V5, and were <bcp14>REQUIRED</bcp14> in the NFSv4.0 specificatio | ||||
n, because | ||||
the Kerberos V5 specification at the time did not specify stronger | the Kerberos V5 specification at the time did not specify stronger | |||
algorithms. | algorithms. | |||
The NFSv4.1 specification does not specify REQUIRED algorithms | The NFSv4.1 specification does not specify <bcp14>REQUIRED</bcp14> algori thms | |||
for Kerberos V5, and instead, the implementor is expected | for Kerberos V5, and instead, the implementor is expected | |||
to track the evolution of the Kerberos V5 standard if and when | to track the evolution of the Kerberos V5 standard if and when | |||
stronger algorithms are specified. | stronger algorithms are specified. | |||
</t> | </t> | |||
<section anchor="krb5_sec_consider" | <section anchor="krb5_sec_consider" numbered="true" toc="defau | |||
title="Security Considerations for Cryptographic Algorithms in Kerberos V5"> | lt"> | |||
<t> | <name>Security Considerations for Cryptographic Algorithms i | |||
n Kerberos V5</name> | ||||
<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> <!-- Kerberos V5 --> | ||||
</section> <!-- Security mechanisms for NFSv4.1 --> | </section> | |||
<section anchor="GSS_Server_Principal" title="GSS Server Principal"> | <section anchor="GSS_Server_Principal" numbered="true" toc="default"> | |||
<t> | <name>GSS Server Principal</name> | |||
<t> | ||||
Regardless of what security mechanism under RPCSEC_GSS | Regardless of what security mechanism under RPCSEC_GSS | |||
is being used, the NFS server MUST 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: | |||
<figure> | </t> | |||
<artwork> | <artwork name="" type="" align="left" alt=""><![CDATA[ | |||
service@hostname | service@hostname | |||
</artwork> | ]]></artwork> | |||
</figure> | <t> | |||
</t> | ||||
<t> | ||||
For NFS, the "service" element is | For NFS, the "service" element is | |||
<figure> | </t> | |||
<artwork> | <artwork name="" type="" align="left" alt=""><![CDATA[ | |||
nfs | nfs | |||
</artwork> | ]]></artwork> | |||
</figure> | <t> | |||
</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 RECOMMENDED: | V5, the following form is <bcp14>RECOMMENDED</bcp14>: | |||
<figure> | </t> | |||
<artwork> | <artwork name="" type="" align="left" alt=""><![CDATA[ | |||
nfs/hostname | nfs/hostname | |||
</artwork> | ]]></artwork> | |||
</figure> | </section> | |||
</t> | </section> | |||
</section> <!-- GSS Server Principal --> | </section> | |||
</section> <!-- RPCSEC_GSS and Security Services --> | </section> | |||
</section> <!-- RPC Security Flavors --> | </section> | |||
</section> <!-- RPC-based Security --> | ||||
</section> <!-- RPC and XDR --> | ||||
<section anchor="COMPOUND_and_CB_COMPOUND" title="COMPOUND and CB_COMPOUND"> | <section anchor="COMPOUND_and_CB_COMPOUND" numbered="true" toc="default"> | |||
<t> | <name>COMPOUND and CB_COMPOUND</name> | |||
<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 | |||
perform the sorts of functions performed by traditional | perform the sorts of functions performed by traditional | |||
NFS procedures. | NFS procedures. | |||
</t> | </t> | |||
<t> | <t> | |||
The operations combined within a COMPOUND | The operations combined within a COMPOUND | |||
request are evaluated in order by the server, without | request are evaluated in order by the server, without | |||
any atomicity guarantees. A limited set of facilities | any atomicity guarantees. A limited set of facilities | |||
exist to pass results from one operation to another. Once an | exist to pass results from one operation to another. Once an | |||
operation returns a failing result, the evaluation ends | operation returns a failing result, the evaluation ends | |||
and the results of all | and the results of all | |||
evaluated operations are returned to the client. | evaluated operations are returned to the client. | |||
</t> | </t> | |||
<t> | <t> | |||
With the use of the COMPOUND procedure, the client is able to build | With the use of the COMPOUND procedure, the client is able to build | |||
simple or complex requests. These COMPOUND requests allow for a | simple or complex requests. These COMPOUND requests allow for a | |||
reduction in the number of RPCs needed for logical file system | reduction in the number of RPCs needed for logical file system | |||
operations. For example, multi-component look up requests can | operations. For example, multi-component look up requests can | |||
be constructed by combining multiple LOOKUP operations. Those | be constructed by combining multiple LOOKUP operations. Those | |||
can be further combined with operations such as GETATTR, READDIR, | can be further combined with operations such as GETATTR, READDIR, | |||
or OPEN plus READ to do more complicated sets of operation without | or OPEN plus READ to do more complicated sets of operation without | |||
incurring additional latency. | incurring additional latency. | |||
</t> | </t> | |||
<t> | <t> | |||
NFSv4.1 also contains a considerable set of | NFSv4.1 also contains a considerable set of | |||
callback operations in which the server makes an RPC | callback operations in which the server makes an RPC | |||
directed at the client. Callback RPCs have a similar | directed at the client. Callback RPCs have a similar | |||
structure to that of the normal server requests. | structure to that of the normal server requests. | |||
In all minor versions of the NFSv4 protocol, | In all minor versions of the NFSv4 protocol, | |||
there are two callback RPC procedures: | there are two callback RPC procedures: | |||
CB_NULL and CB_COMPOUND. The CB_COMPOUND procedure is defined | CB_NULL and CB_COMPOUND. The CB_COMPOUND procedure is defined | |||
in an analogous fashion to that of COMPOUND | in an analogous fashion to that of COMPOUND | |||
with its own set of callback operations. | with its own set of callback operations. | |||
</t> | </t> | |||
<t> | <t> | |||
The addition of new server and callback operations within the | The addition of new server and callback operations within the | |||
COMPOUND and CB_COMPOUND request | COMPOUND and CB_COMPOUND request | |||
framework provides a means of extending the protocol in | framework provides a means of extending the protocol in | |||
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> <!-- COMPOUND and CB_COMPOUND --> | </section> | |||
<section anchor="Client_Identifiers" | <section anchor="Client_Identifiers" numbered="true" toc="default"> | |||
title="Client Identifiers and Client Owners"> | <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 | |||
by a client ID. A client ID is a 64-bit identifier | by a client ID. A client ID is a 64-bit identifier | |||
representing a specific client at a given time. | representing a specific client at a given time. | |||
The client ID is changed whenever the client re-initializes, | The client ID is changed whenever the client re-initializes, | |||
and may change when the server re-initializes. | and may change when the server re-initializes. | |||
Client IDs are used to support lock identification | Client IDs are used to support lock identification | |||
and crash recovery. | and crash recovery. | |||
</t> | </t> | |||
<t> | <t> | |||
During steady state operation, | During steady state operation, | |||
the client ID associated with each operation | the client ID associated with each operation | |||
is derived from the session (see <xref target="Session" | is derived from the session (see <xref target="Session" format="default"/>) | |||
/>) on which the operation is sent. A session is associated with | on which the operation is sent. A session is associated with | |||
a client ID when the session is created. | a client ID when the session is created. | |||
</t> | </t> | |||
<t> | <t> | |||
Unlike NFSv4.0, the only NFSv4.1 operations possible before a | Unlike NFSv4.0, the only NFSv4.1 operations possible before a | |||
client ID is established are those needed to | client ID is established are those needed to | |||
establish the client ID. | establish the client ID. | |||
</t> | </t> | |||
<t> | <t> | |||
A sequence of an EXCHANGE_ID operation followed by a | A sequence of an EXCHANGE_ID operation followed by a | |||
CREATE_SESSION operation using that client ID | CREATE_SESSION operation using that client ID | |||
(eir_clientid as returned from EXCHANGE_ID) | (eir_clientid as returned from EXCHANGE_ID) | |||
is required to establish and confirm the | is required to establish and confirm the | |||
client ID on the server. Establishment of identification by a | client ID on the server. Establishment of identification by a | |||
new incarnation of the client also has the effect of immediately | new incarnation of the client also has the effect of immediately | |||
releasing any locking state that a previous incarnation of that | releasing any locking state that a previous incarnation of that | |||
same client might have had on the server. Such released state | same client might have had on the server. Such released state | |||
would include all byte-range lock, share reservation, layout state, and -- w here the server supports neither the CLAIM_DELEGATE_PREV nor CLAIM_DELEG_CUR_FH claim types -- all delegation state associated with the same client with the sam e | would include all byte-range lock, share reservation, layout state, and -- w here the server supports neither the CLAIM_DELEGATE_PREV nor CLAIM_DELEG_CUR_FH claim types -- all delegation state associated with the same client with the sam e | |||
identity. For discussion of delegation state recovery, see | identity. For discussion of delegation state recovery, see | |||
<xref target="delegation_recovery" />. For discussion of layout state | <xref target="delegation_recovery" format="default"/>. For discussion of lay | |||
recovery, see <xref target="pnfs_client_recovery" />. | out state | |||
</t> | recovery, see <xref target="pnfs_client_recovery" format="default"/>. | |||
<t> | </t> | |||
<t> | ||||
Releasing such state requires that the server be able to determine | Releasing such state requires that the server be able to determine | |||
that one client instance is the successor of another. Where this | that one client instance is the successor of another. Where this | |||
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" />) | (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> | |||
<t> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
struct client_owner4 { | struct client_owner4 { | |||
verifier4 co_verifier; | verifier4 co_verifier; | |||
opaque co_ownerid<NFS4_OPAQUE_LIMIT>; | opaque co_ownerid<NFS4_OPAQUE_LIMIT>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
</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 | |||
is different than what the server has previously | is different than what the server has previously | |||
recorded for the identified client (as specified in | recorded for the identified client (as specified in | |||
the co_ownerid field). | the co_ownerid field). | |||
</t> | </t> | |||
<t> | <t> | |||
The second field, co_ownerid, is a variable length string that uniquely defi nes | The second field, co_ownerid, is a variable length string that uniquely defi nes | |||
the client so that subsequent instances of the same client bear the | the client so that subsequent instances of the same client bear the | |||
same co_ownerid with a different verifier. | same co_ownerid with a different verifier. | |||
</t> | </t> | |||
<t> | <t> | |||
There are several considerations for how the client | There are several considerations for how the client | |||
generates the co_ownerid string: | generates the co_ownerid string: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The string should be unique so that multiple clients | The string should be unique so that multiple clients | |||
do not present the same string. The consequences of | do not present the same string. The consequences of | |||
two clients presenting the same string range from | two clients presenting the same string range from | |||
one client getting an error to one client having its | one client getting an error to one client having its | |||
leased state abruptly and unexpectedly cancelled. | leased state abruptly and unexpectedly cancelled. | |||
</t> | </li> | |||
<t> | <li> | |||
The string should be selected so that subsequent incarnations | The string should be selected so that subsequent incarnations | |||
(e.g., restarts) of the same client cause the client to present | (e.g., restarts) of the same client cause the client to present | |||
the same string. The implementor | the same string. The implementor | |||
is cautioned from an approach that requires the string to | is cautioned from an approach that requires the string to | |||
be recorded in a local file because this precludes the use | be recorded in a local file because this precludes the use | |||
of the implementation in an environment where there is no local | of the implementation in an environment where there is no local | |||
disk and all file access is from an NFSv4.1 server. | disk and all file access is from an NFSv4.1 server. | |||
</t> | </li> | |||
<t> | <li> | |||
The string should be the same for each server network address that | The string should be the same for each server network address that | |||
the client accesses. | the client accesses. | |||
This way, if a server has multiple interfaces, the client | This way, if a server has multiple interfaces, the client | |||
can trunk traffic over multiple network paths | can trunk traffic over multiple network paths | |||
as described in <xref target="Trunking" />. | as described in <xref target="Trunking" format="default"/>. | |||
(Note: the precise opposite was advised in the NFSv4.0 | (Note: the precise opposite was advised in the NFSv4.0 | |||
specification <xref target="RFC3530" />.) | specification <xref target="RFC3530" format="default"/>.) | |||
</t> | </li> | |||
<t> | <li> | |||
The algorithm for generating the string should not | The algorithm for generating the string should not | |||
assume that the client's network address will not | assume that the client's network address will not | |||
change, unless the client implementation knows it | change, unless the client implementation knows it | |||
is using statically assigned network addresses. | is using statically assigned network addresses. | |||
This includes changes between client incarnations | This includes changes between client incarnations | |||
and even changes while the client is still running | and even changes while the client is still running | |||
in its current incarnation. Thus, with dynamic | in its current incarnation. Thus, with dynamic | |||
address assignment, if the | address assignment, if the | |||
client includes just the client's network address | client includes just the client's network address | |||
in the co_ownerid string, there is a real risk | in the co_ownerid string, there is a real risk | |||
that after the | that after the | |||
client gives up the network address, another | client gives up the network address, another | |||
client, using a similar algorithm for generating | client, using a similar algorithm for generating | |||
the co_ownerid string, would generate a conflicting | the co_ownerid string, would generate a conflicting | |||
co_ownerid string. | co_ownerid string. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Given the above considerations, an example of a well-generated co_ownerid | Given the above considerations, an example of a well-generated co_ownerid | |||
string is one that includes: | string is one that includes: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
If applicable, the client's statically assigned network address. | If applicable, the client's statically assigned network address. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
Additional information that tends to be unique, such as one or more | Additional information that tends to be unique, such as one or more | |||
of: | of: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The client machine's serial number (for privacy reasons, it is best | The client machine's serial number (for privacy reasons, it is best | |||
to perform some one-way function on the serial number). | to perform some one-way function on the serial number). | |||
</t> | </li> | |||
<t> | <li> | |||
A Media Access Control (MAC) address (again, a one-way function shou ld be performed). | A Media Access Control (MAC) address (again, a one-way function shou ld be performed). | |||
</t> | </li> | |||
<t> | <li> | |||
The timestamp of when the NFSv4.1 software was first installed | The timestamp of when the NFSv4.1 software was first installed | |||
on the client (though this is subject to the previously mentioned | on the client (though this is subject to the previously mentioned | |||
caution about using information that is stored in a file, because th e | caution about using information that is stored in a file, because th e | |||
file might only be accessible over NFSv4.1). | file might only be accessible over NFSv4.1). | |||
</t> | </li> | |||
<t> | <li> | |||
A true random number. However, since this number ought to be the sam e | A true random number. However, since this number ought to be the sam e | |||
between client incarnations, this shares the same problem as that of | between client incarnations, this shares the same problem as that of | |||
using the timestamp of the software installation. | using the timestamp of the software installation. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
<t> | <li> | |||
For a user-level NFSv4.1 client, it should contain additional | For a user-level NFSv4.1 client, it should contain additional | |||
information to distinguish the client from other user-level clients | information to distinguish the client from other user-level clients | |||
running on the same host, such as a process identifier or other unique | running on the same host, such as a process identifier or other unique | |||
sequence. | sequence. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The client ID is assigned by the server (the eir_clientid result from EXCHAN GE_ID) | The client ID is assigned by the server (the eir_clientid result from EXCHAN GE_ID) | |||
and should be chosen so that it will not | and should be chosen so that it will not | |||
conflict with a client ID previously assigned by the | conflict with a client ID previously assigned by the | |||
server. This applies across server restarts. | server. This applies across server restarts. | |||
</t> | </t> | |||
<t> | <t> | |||
In the event of a server restart, a client may find | In the event of a server restart, a client may find | |||
out that its current client ID is no longer valid when | out that its current client ID is no longer valid when | |||
it receives an NFS4ERR_STALE_CLIENTID error. The precise | it receives an NFS4ERR_STALE_CLIENTID error. The precise | |||
circumstances depend on the characteristics of the | circumstances depend on the characteristics of the | |||
sessions involved, specifically whether the session is | sessions involved, specifically whether the session is | |||
persistent (see <xref target="Persistence" />), but in | persistent (see <xref target="Persistence" format="default"/>), but in | |||
each case the client will receive this error when it attempts | each case the client will receive this error when it attempts | |||
to establish a new session with the existing client ID and | to establish a new session with the existing client ID and | |||
receives the error NFS4ERR_STALE_CLIENTID, indicating that a new | receives the error NFS4ERR_STALE_CLIENTID, indicating that a new | |||
client ID needs to be obtained via EXCHANGE_ID and the new session | client ID needs to be obtained via EXCHANGE_ID and the new session | |||
established with that client ID. | established with that client ID. | |||
</t> | </t> | |||
<t> | <t> | |||
When a session is not persistent, the client will find out that | When a session is not persistent, the client will find out that | |||
it needs to create a new session as a result of getting an | it needs to create a new session as a result of getting an | |||
NFS4ERR_BADSESSION, since the session in question was lost | NFS4ERR_BADSESSION, since the session in question was lost | |||
as part of a server restart. When the existing client ID is | as part of a server restart. When the existing client ID is | |||
presented to a server as part of creating a session | presented to a server as part of creating a session | |||
and that client ID is not recognized, as would happen after a server | and that client ID is not recognized, as would happen after a server | |||
restart, the server will reject the request with the error | restart, the server will reject the request with the error | |||
NFS4ERR_STALE_CLIENTID. | NFS4ERR_STALE_CLIENTID. | |||
</t> | </t> | |||
<t> | <t> | |||
In the case of the session being persistent, the | In the case of the session being persistent, the | |||
client will re-establish communication using the | client will re-establish communication using the | |||
existing session after the restart. This session | existing session after the restart. This session | |||
will be associated with the existing client ID but | will be associated with the existing client ID but | |||
may only be used to retransmit operations that the | may only be used to retransmit operations that the | |||
client previously transmitted and did not see replies | client previously transmitted and did not see replies | |||
to. Replies to operations that the server previously performed | to. Replies to operations that the server previously performed | |||
will come from the reply cache; otherwise, | will come from the reply cache; otherwise, | |||
NFS4ERR_DEADSESSION will be returned. | NFS4ERR_DEADSESSION will be returned. | |||
Hence, such a session is referred to as "dead". In this situation, | Hence, such a session is referred to as "dead". In this situation, | |||
in order to perform new operations, the client needs to | in order to perform new operations, the client needs to | |||
establish a new session. If an attempt is made to | establish a new session. If an attempt is made to | |||
establish this new session with the existing client ID, | establish this new session with the existing client ID, | |||
the server will reject the request with | the server will reject the request with | |||
NFS4ERR_STALE_CLIENTID. | NFS4ERR_STALE_CLIENTID. | |||
</t> | </t> | |||
<t> | <t> | |||
When NFS4ERR_STALE_CLIENTID is received in either of | When NFS4ERR_STALE_CLIENTID is received in either of | |||
these situations, the client needs to obtain a | these situations, the client needs to obtain a | |||
new client ID by use of the EXCHANGE_ID operation, then | new client ID by use of the EXCHANGE_ID operation, then | |||
use that client ID as the basis of a new session, and | use that client ID as the basis of a new session, and | |||
then proceed to | then proceed to | |||
any other necessary recovery for the server restart case (see | any other necessary recovery for the server restart case (see | |||
<xref target="server_failure" />). | <xref target="server_failure" format="default"/>). | |||
</t> | </t> | |||
<t> | <t> | |||
See the descriptions of EXCHANGE_ID | See the descriptions of EXCHANGE_ID | |||
(<xref target="OP_EXCHANGE_ID" />) and CREATE_SESSION | (<xref target="OP_EXCHANGE_ID" format="default"/>) and CREATE_SESSION | |||
(<xref target="OP_CREATE_SESSION" />) for a complete | (<xref target="OP_CREATE_SESSION" format="default"/>) for a complete | |||
specification of these operations. | specification of these operations. | |||
</t> | </t> | |||
<section title="Upgrade from NFSv4.0 to NFSv4.1" > | <section numbered="true" toc="default"> | |||
<t> | <name>Upgrade from NFSv4.0 to NFSv4.1</name> | |||
<t> | ||||
To facilitate upgrade from NFSv4.0 to NFSv4.1, a server | To facilitate upgrade from NFSv4.0 to NFSv4.1, a server | |||
may compare a value of data type client_owner4 in an EXCHANGE_ID with a | may compare a value of data type client_owner4 in an EXCHANGE_ID with a | |||
value of data type nfs_client_id4 that was established using the SETCLIENTID operation of | value of data type nfs_client_id4 that was established using the SETCLIENTID operation of | |||
NFSv4.0. A server that does so will allow | NFSv4.0. A server that does so will allow | |||
an upgraded client to avoid waiting | an upgraded client to avoid waiting | |||
until the lease (i.e., the lease established by the NFSv4.0 instance | until the lease (i.e., the lease established by the NFSv4.0 instance | |||
client) expires. | client) expires. | |||
This requires that the value of data type client_owner4 be constructed | This requires that the value of data type client_owner4 be constructed | |||
the same way as the value of data type nfs_client_id4. If the latter's | the same way as the value of data type nfs_client_id4. If the latter's | |||
contents included the server's network address (per the | contents included the server's network address (per the | |||
recommendations of the NFSv4.0 specification <xref target="RFC3530" />), and | recommendations of the NFSv4.0 specification <xref target="RFC3530" format=" default"/>), and | |||
the NFSv4.1 client does not wish to use a client | the NFSv4.1 client does not wish to use a client | |||
ID that prevents trunking, it should send two | ID that prevents trunking, it should send two | |||
EXCHANGE_ID operations. The first EXCHANGE_ID will | EXCHANGE_ID operations. The first EXCHANGE_ID will | |||
have a client_owner4 equal to the nfs_client_id4. | have a client_owner4 equal to the nfs_client_id4. | |||
This will clear the state created by the NFSv4.0 | This will clear the state created by the NFSv4.0 | |||
client. The second EXCHANGE_ID will not have the | client. The second EXCHANGE_ID will not have the | |||
server's network address. The state created for the | server's network address. The state created for the | |||
second EXCHANGE_ID will not have to wait for lease | second EXCHANGE_ID will not have to wait for lease | |||
expiration, because there will be no state to expire. | expiration, because there will be no state to expire. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="Server Release of Client ID" > | <name>Server Release of Client ID</name> | |||
<t> | <t> | |||
NFSv4.1 introduces a new operation called | NFSv4.1 introduces a new operation called | |||
DESTROY_CLIENTID (<xref target="OP_DESTROY_CLIENTID" />), | DESTROY_CLIENTID (<xref target="OP_DESTROY_CLIENTID" format="default"/>), | |||
which the client SHOULD use to destroy a client ID it | which the client <bcp14>SHOULD</bcp14> use to destroy a client ID it | |||
no longer needs. This permits graceful, bilateral release of | no longer needs. This permits graceful, bilateral release of | |||
a client ID. The operation cannot be used if there are sessions | a client ID. The operation cannot be used if there are sessions | |||
associated with the client ID, or state with an unexpired lease. | associated with the client ID, or state with an unexpired lease. | |||
</t> | </t> | |||
<t> | <t> | |||
If the server determines that the client holds no associated state | If the server determines that the client holds no associated state | |||
for its client ID (associated state includes unrevoked sessions, | for its client ID (associated state includes unrevoked sessions, | |||
opens, locks, delegations, layouts, and wants), the server MAY | opens, locks, delegations, layouts, and wants), the server <bcp14>MAY</bcp1 4> | |||
choose to unilaterally release the client ID in order to | choose to unilaterally release the client ID in order to | |||
conserve resources. | conserve resources. | |||
If the client | If the client | |||
contacts the server after this release, the server | contacts the server after this release, the server | |||
MUST ensure that the client receives the appropriate error | <bcp14>MUST</bcp14> ensure that the client receives the appropriate error | |||
so that it will use the EXCHANGE_ID/CREATE_SESSION | so that it will use the EXCHANGE_ID/CREATE_SESSION | |||
sequence to establish a new client ID. | sequence to establish a new client ID. | |||
The server ought to be very hesitant to | The server ought to be very hesitant to | |||
release a client ID since the resulting work on the | release a client ID since the resulting work on the | |||
client to recover from such an event will be the same | client to recover from such an event will be the same | |||
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 MUST NOT release the client ID. See <xref | server <bcp14>MUST NOT</bcp14> release the client ID. See <xref target="los | |||
target="loss_of_session" /> for discussion on | s_of_session" format="default"/> for discussion on | |||
releasing inactive sessions. | releasing inactive sessions. | |||
</t> | </t> | |||
</section> <!-- Server Release of Client ID --> | </section> | |||
<section title="Resolving Client Owner Conflicts" anchor="cowner_conflicts"> | <section anchor="cowner_conflicts" numbered="true" toc="default"> | |||
<t> | <name>Resolving Client Owner Conflicts</name> | |||
<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 MUST 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> | |||
When the server gets an EXCHANGE_ID for a | When the server gets an EXCHANGE_ID for a | |||
new incarnation of a client owner that | new incarnation of a client owner that | |||
currently has an old incarnation with state and an unexpired lease, the | currently has an old incarnation with state and an unexpired lease, the | |||
server is allowed to dispose of the state of the | server is allowed to dispose of the state of the | |||
previous incarnation of the client owner if | previous incarnation of the client owner if | |||
one of the following is true: | one of the following is true: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The principal that created the client ID for the client owner | The principal that created the client ID for the client owner | |||
is the same as the principal that is sending the EXCHANGE_ID operation. | is the same as the principal that is sending the EXCHANGE_ID operation. | |||
Note that if the client ID was created with | Note that if the client ID was created with | |||
SP4_MACH_CRED state protection (<xref target="OP_EXCHANGE_ID" />), | SP4_MACH_CRED state protection (<xref target="OP_EXCHANGE_ID" format="def | |||
the principal MUST be based on RPCSEC_GSS authentication, | ault"/>), | |||
the RPCSEC_GSS service used MUST be integrity or | the principal <bcp14>MUST</bcp14> be based on RPCSEC_GSS authentication, | |||
the RPCSEC_GSS service used <bcp14>MUST</bcp14> be integrity or | ||||
privacy, and the | privacy, and the | |||
same GSS mechanism and principal | same GSS mechanism and principal | |||
MUST be used as that used when the client ID | <bcp14>MUST</bcp14> be used as that used when the client ID | |||
was created. | was created. | |||
</t> | </li> | |||
<t> | <li> | |||
The client ID was established with SP4_SSV | The client ID was established with SP4_SSV | |||
protection (<xref target="OP_EXCHANGE_ID" />, | protection (<xref target="OP_EXCHANGE_ID" format="default"/>, | |||
<xref target="protect_state_change" />) | <xref target="protect_state_change" format="default"/>) | |||
and the client sends the EXCHANGE_ID with the | and the client sends the EXCHANGE_ID with the | |||
security flavor set to RPCSEC_GSS using the GSS | security flavor set to RPCSEC_GSS using the GSS | |||
SSV mechanism (<xref target="ssv_mech" />). | SSV mechanism (<xref target="ssv_mech" format="default"/>). | |||
</t> | </li> | |||
<t> | <li> | |||
The client ID was established with SP4_SSV | The client ID was established with SP4_SSV | |||
protection, and under the conditions described herein, | protection, and under the conditions described herein, | |||
the EXCHANGE_ID was sent with SP4_MACH_CRED state protection. | the EXCHANGE_ID was sent with SP4_MACH_CRED state protection. | |||
Because the SSV might not persist | Because the SSV might not persist | |||
across client and server restart, and because | across client and server restart, and because | |||
the first time a client sends EXCHANGE_ID to | the first time a client sends EXCHANGE_ID to | |||
a server it does not have an SSV, the client | a server it does not have an SSV, the client | |||
MAY send the subsequent EXCHANGE_ID without | <bcp14>MAY</bcp14> send the subsequent EXCHANGE_ID without | |||
an SSV RPCSEC_GSS handle. Instead, as with | an SSV RPCSEC_GSS handle. Instead, as with | |||
SP4_MACH_CRED protection, the principal MUST be | SP4_MACH_CRED protection, the principal <bcp14>MUST</bcp14> be | |||
based on RPCSEC_GSS authentication, the RPCSEC_GSS | based on RPCSEC_GSS authentication, the RPCSEC_GSS | |||
service used MUST be integrity or privacy, and the | service used <bcp14>MUST</bcp14> be integrity or privacy, and the | |||
same GSS mechanism and principal MUST be used as | same GSS mechanism and principal <bcp14>MUST</bcp14> be used as | |||
that used when the client ID was created. | that used when the client ID was created. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
If none of the above situations apply, the server | If none of the above situations apply, the server | |||
MUST return NFS4ERR_CLID_INUSE. | <bcp14>MUST</bcp14> return NFS4ERR_CLID_INUSE. | |||
</t> | </t> | |||
<t> | <t> | |||
If the server accepts the principal and co_ownerid | If the server accepts the principal and co_ownerid | |||
as matching that which created the client ID, and | as matching that which created the client ID, and | |||
the co_verifier in the EXCHANGE_ID differs from the | the co_verifier in the EXCHANGE_ID differs from the | |||
co_verifier used when the client ID was created, | co_verifier used when the client ID was created, | |||
then after the server receives a CREATE_SESSION that | then after the server receives a CREATE_SESSION that | |||
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" />) or | (<xref target="OP_EXCHANGE_ID" format="default"/>) or | |||
is attempting trunking (<xref target="Trunking" />), | is attempting trunking (<xref target="Trunking" format="default"/>), | |||
the server MUST NOT delete state. | the server <bcp14>MUST NOT</bcp14> delete state. | |||
</t> | ||||
</section> <!-- Handling Client Owner Conflicts --> | </t> | |||
</section> <!-- Client Identifiers --> | </section> | |||
<section anchor="Server_Owners" title="Server Owners"> | </section> | |||
<t> | <section anchor="Server_Owners" numbered="true" toc="default"> | |||
<name>Server Owners</name> | ||||
<t> | ||||
The server owner is similar to a client owner | The server owner is similar to a client owner | |||
(<xref target="Client_Identifiers" />), 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> | |||
<t> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
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>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
</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 | |||
(as defined in <xref target="intro_definitions" />). If | (as defined in <xref target="intro_definitions" format="default"/>). If | |||
the so_minor_id fields are also the same, then not only | the so_minor_id fields are also the same, then not only | |||
do both connections connect to the same server, but the | do both connections connect to the same server, but the | |||
session can be shared across both | session can be shared across both | |||
connections. The reader is cautioned that multiple | connections. The reader is cautioned that multiple | |||
servers may deliberately or accidentally claim to have | servers may deliberately or accidentally claim to have | |||
the same so_major_id or so_major_id/so_minor_id; the | the same so_major_id or so_major_id/so_minor_id; the | |||
reader should examine Sections <xref target="Trunking" format="counter" /> an | reader should examine Sections <xref target="Trunking" format="counter"/> and | |||
d | <xref target="OP_EXCHANGE_ID" format="counter"/> in order to avoid | |||
<xref target="OP_EXCHANGE_ID" format="counter" /> in order to avoid | ||||
acting on falsely matching server owner values. | acting on falsely matching server owner values. | |||
</t> | </t> | |||
<t> | <t> | |||
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" />). 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" />). | (see <xref target="Trunking" format="default"/>). | |||
</t> | </t> | |||
</section> <!-- Server Owners --> | </section> | |||
<section anchor="Security_Service_Negotiation" title="Security Service Negotiat | <section anchor="Security_Service_Negotiation" numbered="true" toc="default"> | |||
ion"> | <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. | |||
These points can be considered security policy boundaries, | These points can be considered security policy boundaries, | |||
and, in some NFS implementations, are tied to NFS export points. | and, in some NFS implementations, are tied to NFS export points. | |||
In turn, the NFS server may be configured such that each | In turn, the NFS server may be configured such that each | |||
of these security policy boundaries may have different or multiple | of these security policy boundaries may have different or multiple | |||
security mechanisms in use. | security mechanisms in use. | |||
</t> | </t> | |||
<t> | <t> | |||
The security negotiation between client and server | The security negotiation between client and server | |||
SHOULD be done with a secure channel to eliminate | <bcp14>SHOULD</bcp14> be done with a secure channel to eliminate | |||
the possibility of a third party intercepting the | the possibility of a third party intercepting the | |||
negotiation sequence and forcing the client and server | negotiation sequence and forcing the client and server | |||
to choose a lower level of security than required or | to choose a lower level of security than required or | |||
desired. See | desired. See | |||
<xref target="SECCON" /> for further discussion. | <xref target="SECCON" format="default"/> for further discussion. | |||
</t> | </t> | |||
<section anchor="NFSv4_Security_Tuples" numbered="true" toc="default"> | ||||
<section anchor="NFSv4_Security_Tuples" title="NFSv4.1 Security Tuples"> | <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" />) and, if the flavor | (see <xref target="RPC_Security_Flavors" format="default"/>) and, if the flav or | |||
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> <!-- NFSv4.1 Security Tuples --> | </section> | |||
<section anchor="SECINFO_and_SECINFO_NO_NAME" title="SECINFO and SECINFO_NO_NA | <section anchor="SECINFO_and_SECINFO_NO_NAME" numbered="true" toc="default"> | |||
ME"> | <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 | |||
and force the client to negotiate a new security tuple. | and force the client to negotiate a new security tuple. | |||
</t> | </t> | |||
<t> | <t> | |||
Where the use of different security tuples would affect the type of | Where the use of different security tuples would affect the type of | |||
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> <!-- SECINFO and SECINFO_NO_NAME --> | </section> | |||
<section anchor="Security_Error" title="Security Error"> | <section anchor="Security_Error" numbered="true" toc="default"> | |||
<t> | <name>Security Error</name> | |||
<t> | ||||
Based on the assumption that each NFSv4.1 client | Based on the assumption that each NFSv4.1 client | |||
and server MUST 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 | |||
NFS error of NFS4ERR_WRONGSEC. This error allows the | NFS error of NFS4ERR_WRONGSEC. This error allows the | |||
server to notify the client that the security tuple | server to notify the client that the security tuple | |||
currently being used contravenes the server's | currently being used contravenes the server's | |||
security policy. The client is then responsible for | security policy. The client is then responsible for | |||
determining (see <xref target="using_secinfo" />) what | determining (see <xref target="using_secinfo" format="default"/>) what | |||
security tuples are available at the server and choosing | security tuples are available at the server and choosing | |||
one that is appropriate for the client. | one that is appropriate for the client. | |||
</t> | </t> | |||
<section anchor="using_secinfo" numbered="true" toc="default"> | ||||
<section anchor="using_secinfo" title="Using NFS4ERR_WRONGSEC, SECINFO, and SE | <name>Using NFS4ERR_WRONGSEC, SECINFO, and SECINFO_NO_NAME</name> | |||
CINFO_NO_NAME"> | <t> | |||
<t> | ||||
This section explains the mechanics of NFSv4.1 security negotiation. | This section explains the mechanics of NFSv4.1 security negotiation. | |||
</t> | </t> | |||
<section anchor="putfh_series" numbered="true" toc="default"> | ||||
<section anchor="putfh_series" title="Put Filehandle Operations"> | <name>Put Filehandle Operations</name> | |||
<t> | ||||
<t> | ||||
The term "put filehandle operation" refers to | The term "put filehandle operation" refers to | |||
PUTROOTFH, PUTPUBFH, PUTFH, and RESTOREFH. Each of the subsections | PUTROOTFH, PUTPUBFH, PUTFH, and RESTOREFH. Each of the subsections | |||
herein describes how the server handles a subseries of operations | herein describes how the server handles a subseries of operations | |||
that starts with a put filehandle operation. | that starts with a put filehandle operation. | |||
</t> | </t> | |||
<section anchor="PUTFHplusSAVEFH" numbered="true" toc="default"> | ||||
<section anchor="PUTFHplusSAVEFH" | <name>Put Filehandle Operation + SAVEFH</name> | |||
title="Put Filehandle Operation + SAVEFH"> | <t> | |||
<t> | ||||
The client is saving a filehandle for a future | The client is saving a filehandle for a future | |||
RESTOREFH, LINK, or RENAME. SAVEFH MUST NOT | 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 | situations described in the other subsections of <xref target="putfh_series" | |||
target="putfh_series"/> apply. | format="default"/> apply. | |||
</t> | </t> | |||
</section> <!-- Put Filehandle Operation + SAVEFH --> | </section> | |||
<section anchor="PUTFHplusPUTFH" | <section anchor="PUTFHplusPUTFH" numbered="true" toc="default"> | |||
title="Two or More Put Filehandle Operations"> | <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 | |||
MUST NOT 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"/>. | to <xref target="PUTFHplusLOOKUP" format="default"/>. | |||
</t> | </t> | |||
</section> <!-- PUTFH + PUTFH --> | </section> | |||
<section anchor="PUTFHplusLOOKUP" | <section anchor="PUTFHplusLOOKUP" numbered="true" toc="default"> | |||
title="Put Filehandle Operation + LOOKUP (or OPEN of an Existing Name)"> | <name>Put Filehandle Operation + LOOKUP (or OPEN of an Existing | |||
<t> | Name)</name> | |||
<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 | |||
the child. | the child. | |||
The server implementation may decide whether to impose | The server implementation may decide whether to impose | |||
any restrictions on security policy administration. | any restrictions on security policy administration. | |||
There are at least three approaches (sec_policy_child is | There are at least three approaches (sec_policy_child is | |||
the tuple set of the child export, sec_policy_parent is | the tuple set of the child export, sec_policy_parent is | |||
that of the parent). | that of the parent). | |||
</t> | </t> | |||
<t> | <ol spacing="normal" type="(%c)"> | |||
<list style="format (%c)"> | <li> | |||
<t> | ||||
sec_policy_child <= sec_policy_parent (<= for subset). This | sec_policy_child <= sec_policy_parent (<= for subset). This | |||
means that the set of security tuples specified on the | means that the set of security tuples specified on the | |||
security policy of a child directory is always a subset | security policy of a child directory is always a subset | |||
of its parent directory. | of its parent directory. | |||
</t> | </li> | |||
<t> | <li> | |||
sec_policy_child ^ sec_policy_parent != {} (^ for intersection, {} | sec_policy_child ^ sec_policy_parent != {} (^ for intersection, {} | |||
for the empty set). This means that the set of security tuples specified | for the empty set). This means that the set of security tuples specified | |||
on the security policy of a child directory always has a non-empty intersect ion | on the security policy of a child directory always has a non-empty intersect ion | |||
with that of the parent. | with that of the parent. | |||
</t> | </li> | |||
<t> | <li> | |||
sec_policy_child ^ sec_policy_parent == {}. This means that the | sec_policy_child ^ sec_policy_parent == {}. This means that the | |||
set of security tuples specified on the security policy of a child directory | set of security tuples specified on the security policy of a child directory | |||
may not intersect with that of the parent. In other words, there | may not intersect with that of the parent. In other words, there | |||
are no restrictions on how the system administrator may | are no restrictions on how the system administrator may | |||
set up these tuples. | set up these tuples. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | <t> | |||
<t> | ||||
In order for a server to support approaches (b) | In order for a server to support approaches (b) | |||
(for the case when a client chooses a flavor that is | (for the case when a client chooses a flavor that is | |||
not a member of sec_policy_parent) and (c), the put | not a member of sec_policy_parent) and (c), the put | |||
filehandle operation cannot return NFS4ERR_WRONGSEC | filehandle operation cannot return NFS4ERR_WRONGSEC | |||
when there is a security tuple mismatch. Instead, | when there is a security tuple mismatch. Instead, | |||
it should be returned from the LOOKUP (or OPEN by | it should be returned from the LOOKUP (or OPEN by | |||
existing component name) that follows. | existing component name) that follows. | |||
</t> | </t> | |||
<t> | <t> | |||
Since the above guideline does not contradict approach | Since the above guideline does not contradict approach | |||
(a), it should be followed in general. Even if approach | (a), it should be followed in general. Even if approach | |||
(a) is implemented, it is possible for the security | (a) is implemented, it is possible for the security | |||
tuple used to be acceptable for the target of LOOKUP | tuple used to be acceptable for the target of LOOKUP | |||
but not for the filehandles used in the put filehandle operation. The | but not for the filehandles used in the put filehandle operation. The | |||
put filehandle operation | put filehandle operation | |||
could be a PUTROOTFH or PUTPUBFH, where the | could be a PUTROOTFH or PUTPUBFH, where the | |||
client cannot know the security tuples for the root | client cannot know the security tuples for the root | |||
or public filehandle. Or the security policy for the | or public filehandle. Or the security policy for the | |||
filehandle used by the put filehandle operation | filehandle used by the put filehandle operation | |||
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 MUST NOT 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> <!-- PUTFH + LOOKUP --> | </section> | |||
<section anchor="PUTFHplusLOOKUPP" title="Put Filehandle Operation + LOOKUPP" | <section anchor="PUTFHplusLOOKUPP" numbered="true" toc="default"> | |||
> | <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" />, 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 | |||
MUST NOT return NFS4ERR_WRONGSEC. | <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC. | |||
If the server does not support SECINFO_NO_NAME, the client's | If the server does not support SECINFO_NO_NAME, the client's | |||
only recourse is to send the put filehandle operation, | only recourse is to send the put filehandle operation, | |||
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 MUST NOT 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> <!-- PUTFH + LOOKUPP --> | </section> | |||
<section title="Put Filehandle Operation + SECINFO/SECINFO_NO_NAME" | <section anchor="PUTFHplusSECINFO" numbered="true" toc="default"> | |||
anchor="PUTFHplusSECINFO"> | <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 | |||
operation or the child file object indicated in SECINFO (or any parent direc tory | operation or the child file object indicated in SECINFO (or any parent direc tory | |||
indicated in SECINFO_NO_NAME). Of course, the server has to be | indicated in SECINFO_NO_NAME). Of course, the server has to be | |||
configured for whatever security | configured for whatever security | |||
tuple the client selects; otherwise, the request will | tuple the client selects; otherwise, the request will | |||
fail at the RPC layer with an appropriate authentication error. | fail at the RPC layer with an appropriate authentication error. | |||
</t> | </t> | |||
<t> | <t> | |||
In theory, there is no connection between the security | In theory, there is no connection between the security | |||
flavor used by SECINFO or SECINFO_NO_NAME and those | flavor used by SECINFO or SECINFO_NO_NAME and those | |||
supported by the security policy. But in practice, the | supported by the security policy. But in practice, the | |||
client may start looking for strong flavors from those | client may start looking for strong flavors from those | |||
supported by the security policy, followed by those in | supported by the security policy, followed by those in | |||
the REQUIRED set. | the <bcp14>REQUIRED</bcp14> set. | |||
</t> | </t> | |||
<t> | <t> | |||
The NFSv4.1 server MUST NOT 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 MUST NOT return NFS4ERR_WRONGSEC from SECINFO or | The NFSv4.1 server <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC from SECI NFO or | |||
SECINFO_NO_NAME. | SECINFO_NO_NAME. | |||
</t> | </t> | |||
</section> <!-- PUTFH + SECINFO --> | </section> | |||
<section anchor="PUTFHplusNothing" title="Put Filehandle Operation + Nothing" | <section anchor="PUTFHplusNothing" numbered="true" toc="default"> | |||
> | <name>Put Filehandle Operation + Nothing</name> | |||
<t> | <t> | |||
The NFSv4.1 server MUST NOT return NFS4ERR_WRONGSEC. | The NFSv4.1 server <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC. | |||
</t> | </t> | |||
</section> <!-- PUTFH + Nothing --> | </section> | |||
<section anchor="PUTFHplusAnythingElse" title="Put Filehandle Operation + Any | <section anchor="PUTFHplusAnythingElse" numbered="true" toc="default"> | |||
thing Else"> | <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 MUST | put filehandle operation <bcp14>MUST</bcp14> | |||
return NFS4ERR_WRONGSEC when there is a security tuple | return NFS4ERR_WRONGSEC when there is a security tuple | |||
mismatch. This avoids the complexity of | mismatch. This avoids the complexity of | |||
adding NFS4ERR_WRONGSEC as an allowable error to every | adding NFS4ERR_WRONGSEC as an allowable error to every | |||
other operation. | other operation. | |||
</t> | </t> | |||
<t> | <t> | |||
A COMPOUND containing the series put filehandle | A COMPOUND containing the series put filehandle | |||
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 MUST NOT 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> <!-- PUTFH + Anything Else --> | </section> | |||
<section anchor="aftersecinfo" title="Operations after SECINFO and SECINFO_NO | <section anchor="aftersecinfo" numbered="true" toc="default"> | |||
_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"/>), | 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 | return NFS4ERR_WRONGSEC. By rule (see <xref target="PUTFHplusAnythingElse" | |||
target="PUTFHplusAnythingElse"/>), READ cannot return | 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 curren t filehandle for | filehandle (note that this is a change from NFSv4.0). This leaves no curren t filehandle for | |||
READ to use, and READ returns NFS4ERR_NOFILEHANDLE. | READ to use, and READ returns NFS4ERR_NOFILEHANDLE. | |||
</t> | </t> | |||
</section> | ||||
</section> <!-- Operations after SECINFO and SECINFO_NO_NAME" --> | ||||
</section> | </section> | |||
<section anchor="link_rename" title="LINK and RENAME" > | <section anchor="link_rename" numbered="true" toc="default"> | |||
<t> | <name>LINK and RENAME</name> | |||
<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 MAY 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 | |||
saved filehandle rejects the security flavor used in the | saved filehandle rejects the security flavor used in the | |||
COMPOUND request's credentials. If the server does so, | COMPOUND request's credentials. If the server does so, | |||
then if there is no intersection between the security | then if there is no intersection between the security | |||
policies of saved and current filehandles, this means that it | policies of saved and current filehandles, this means that it | |||
will be impossible for the client to perform the intended | will be impossible for the client to perform the intended | |||
LINK or RENAME operation. | LINK or RENAME operation. | |||
</t> | </t> | |||
<t> | <t> | |||
For example, suppose the client sends this COMPOUND | For example, suppose the client sends this COMPOUND | |||
request: SEQUENCE, PUTFH bFH, SAVEFH, PUTFH aFH, | request: SEQUENCE, PUTFH bFH, SAVEFH, PUTFH aFH, | |||
RENAME "c" "d", where filehandles bFH and aFH refer | RENAME "c" "d", where filehandles bFH and aFH refer | |||
to different directories. Suppose no common security | to different directories. Suppose no common security | |||
tuple exists between the security policies of aFH and | tuple exists between the security policies of aFH and | |||
bFH. If the client sends the request using credentials | bFH. If the client sends the request using credentials | |||
acceptable to bFH's security policy but not aFH's | acceptable to bFH's security policy but not aFH's | |||
policy, then the PUTFH aFH operation will fail with | policy, then the PUTFH aFH operation will fail with | |||
NFS4ERR_WRONGSEC. After a SECINFO_NO_NAME request, | NFS4ERR_WRONGSEC. After a SECINFO_NO_NAME request, | |||
the client sends SEQUENCE, PUTFH bFH, SAVEFH, PUTFH | the client sends SEQUENCE, PUTFH bFH, SAVEFH, PUTFH | |||
aFH, RENAME "c" "d", using credentials acceptable to | aFH, RENAME "c" "d", using credentials acceptable to | |||
aFH's security policy but not bFH's policy. The server | aFH's security policy but not bFH's policy. The server | |||
returns NFS4ERR_WRONGSEC on the RENAME operation. | returns NFS4ERR_WRONGSEC on the RENAME operation. | |||
</t> | </t> | |||
<t> | <t> | |||
To prevent a client from an endless sequence of a | To prevent a client from an endless sequence of a | |||
request containing LINK or RENAME, followed by a request | request containing LINK or RENAME, followed by a request | |||
containing SECINFO_NO_NAME or SECINFO, the server MUST detect | containing SECINFO_NO_NAME or SECINFO, the server <bcp14>MUST</bcp14> detect | |||
when the security policies of the current and saved | when the security policies of the current and saved | |||
filehandles have no mutually acceptable security tuple, | filehandles have no mutually acceptable security tuple, | |||
and MUST NOT return NFS4ERR_WRONGSEC from LINK or RENAME | and <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC from LINK or RENAME | |||
in that situation. Instead | in that situation. Instead | |||
the server MUST do one of two things: | the server <bcp14>MUST</bcp14> do one of two things: | |||
<list style='symbols'> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <li> | |||
The server can return NFS4ERR_XDEV. | The server can return NFS4ERR_XDEV. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
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. | |||
</t> | </li> | |||
</ul> | ||||
</list> | </section> | |||
</section> | ||||
</t> | </section> | |||
</section> | </section> | |||
</section> <!-- Using NFS4ERR_WRONGSEC, SECINFO, and SECINFO_NO_NAME --> | ||||
</section> <!-- Security Error --> | ||||
</section> <!-- Security Service Negotiation --> | ||||
<section anchor="minor_versioning" title="Minor Versioning"> | <section anchor="minor_versioning" numbered="true" toc="default"> | |||
<t> | <name>Minor Versioning</name> | |||
<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 | |||
future accepted minor version will be | future accepted minor version will be | |||
documented in one or more Standards Track RFCs. | documented in one or more Standards Track RFCs. | |||
Minor version 0 of the NFSv4 protocol is represented by | Minor version 0 of the NFSv4 protocol is represented by | |||
<xref target="RFC3530" />, and minor version 1 is represented by | <xref target="RFC3530" format="default"/>, and minor version 1 is represented by | |||
this RFC. | this RFC. | |||
The COMPOUND and CB_COMPOUND | The COMPOUND and CB_COMPOUND | |||
procedures support the encoding of the minor version | procedures support the encoding of the minor version | |||
being requested by the client. | being requested by the client. | |||
</t> | </t> | |||
<t> | <t> | |||
The following items represent the basic rules for the development of | The following items represent the basic rules for the development of | |||
minor versions. Note that a future minor version may modify | minor versions. Note that a future minor version may modify | |||
or add to the following rules as part of the minor version definition. | or add to the following rules as part of the minor version definition. | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
<t> | ||||
Procedures are not added or deleted. | Procedures are not added or deleted. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
To maintain the general RPC model, NFSv4 minor versions will | To maintain the general RPC model, NFSv4 minor versions will | |||
not add to or delete procedures from the NFS program. | not add to or delete procedures from the NFS program. | |||
</t> | </t> | |||
</li> | ||||
<t> | <li> | |||
<t> | ||||
Minor versions may add operations to the COMPOUND and CB_COMPOUND | Minor versions may add operations to the COMPOUND and CB_COMPOUND | |||
procedures. | procedures. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
The addition of operations to the COMPOUND and CB_COMPOUND procedures | The addition of operations to the COMPOUND and CB_COMPOUND procedures | |||
does not affect the RPC model. | does not affect the RPC model. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
Minor versions may append attributes to the bitmap4 that represents | Minor versions may append attributes to the bitmap4 that represents | |||
sets of attributes and to the fattr4 that represents sets of attribute | sets of attributes and to the fattr4 that represents sets of attribute | |||
values. | values. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
This allows for the expansion of the attribute model to allow for | This allows for the expansion of the attribute model to allow for | |||
future growth or adaptation. | future growth or adaptation. | |||
</t> | </t> | |||
</li> | ||||
<t> | <li> | |||
<t> | ||||
Minor version X must append any new attributes after the last | Minor version X must append any new attributes after the last | |||
documented attribute. | documented attribute. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
Since attribute results are specified as an opaque array of | Since attribute results are specified as an opaque array of | |||
per-attribute, XDR-encoded results, the complexity of adding new | per-attribute, XDR-encoded results, the complexity of adding new | |||
attributes in the midst of the current definitions would be too | attributes in the midst of the current definitions would be too | |||
burdensome. | burdensome. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ul> | |||
</li> | ||||
<t> | <li> | |||
<t> | ||||
Minor versions must not modify the structure of an existing | Minor versions must not modify the structure of an existing | |||
operation's arguments or results. | operation's arguments or results. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
Again, the complexity of handling multiple structure definitions for a | Again, the complexity of handling multiple structure definitions for a | |||
single operation is too burdensome. New operations should be added | single operation is too burdensome. New operations should be added | |||
instead of modifying existing structures for a minor version. | instead of modifying existing structures for a minor version. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
This rule does not preclude the following adaptations in a minor version: | This rule does not preclude the following adaptations in a minor version: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
adding bits to flag fields, such as new attributes to GETATTR's bitmap4 | adding bits to flag fields, such as new attributes to GETATTR's bitmap4 | |||
data type, and providing corresponding variants of opaque arrays, | data type, and providing corresponding variants of opaque arrays, | |||
such as a notify4 used together with such bitmaps | such as a notify4 used together with such bitmaps | |||
</t> | </li> | |||
<t> | <li> | |||
adding bits to existing attributes like ACLs that have flag words | adding bits to existing attributes like ACLs that have flag words | |||
</t> | </li> | |||
<t> | <li> | |||
extending enumerated types (including NFS4ERR_*) with new values | extending enumerated types (including NFS4ERR_*) with new values | |||
</t> | </li> | |||
<t> | <li> | |||
adding cases to a switched union | adding cases to a switched union | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
Minor versions must not modify the structure of existing attributes. | Minor versions must not modify the structure of existing attributes. | |||
</t> | </li> | |||
<li> | ||||
<t> | <t> | |||
Minor versions must not delete operations. | Minor versions must not delete operations. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
This prevents the potential reuse of a particular operation "slot" in | This prevents the potential reuse of a particular operation "slot" in | |||
a future minor version. | a future minor version. | |||
</t> | </t> | |||
</li> | ||||
<t> | <li> | |||
Minor versions must not delete attributes. | Minor versions must not delete attributes. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
Minor versions must not delete flag bits or enumeration values. | Minor versions must not delete flag bits or enumeration values. | |||
</t> | </li> | |||
<li> | ||||
<t> | <t> | |||
Minor versions may declare an operation MUST NOT be implemented. | Minor versions may declare an operation <bcp14>MUST NOT</bcp14> be implemented. | |||
<vspace blankLines='1' /> | </t> | |||
Specifying that an operation MUST NOT be implemented is equivalent | <t> | |||
Specifying that an operation <bcp14>MUST NOT</bcp14> be implemented is equivale | ||||
nt | ||||
to obsoleting an operation. For the client, it means that the | to obsoleting an operation. For the client, it means that the | |||
operation MUST NOT be sent to the server. For the server, an NFS | operation <bcp14>MUST NOT</bcp14> be sent to the server. For the server, an NF S | |||
error can be returned as opposed to "dropping" the request as an XDR | error can be returned as opposed to "dropping" the request as an XDR | |||
decode error. This approach allows for the obsolescence of an | decode error. This approach allows for the obsolescence of an | |||
operation while maintaining its structure so that a future minor version can re introduce the operation. | operation while maintaining its structure so that a future minor version can re introduce the operation. | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
Minor versions may declare that an attribute MUST NOT be implemented. | <li> | |||
</t> | Minor versions may declare that an attribute <bcp14>MUST NOT</bcp14> be impleme | |||
<t> | nted. | |||
Minor versions may declare that a flag bit or enumeration value MUST NOT | </li> | |||
<li> | ||||
Minor versions may declare that a flag bit or enumeration value <bcp14>MUST NOT | ||||
</bcp14> | ||||
be implemented. | be implemented. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | </li> | |||
<li> | ||||
<t> | Minor versions may downgrade features from <bcp14>REQUIRED</bcp14> to <bcp14>RE | |||
Minor versions may downgrade features from REQUIRED to RECOMMENDED, | COMMENDED</bcp14>, | |||
or RECOMMENDED to OPTIONAL. | or <bcp14>RECOMMENDED</bcp14> to <bcp14>OPTIONAL</bcp14>. | |||
</t> | </li> | |||
<li> | ||||
<t> | Minor versions may upgrade features from <bcp14>OPTIONAL</bcp14> to <bcp14>RECO | |||
Minor versions may upgrade features from OPTIONAL to RECOMMENDED, or | MMENDED</bcp14>, or | |||
RECOMMENDED to REQUIRED. | <bcp14>RECOMMENDED</bcp14> to <bcp14>REQUIRED</bcp14>. | |||
</t> | </li> | |||
<li> | ||||
<t> | A client and server that support minor version X <bcp14>SHOULD</bcp14> support | |||
A client and server that support minor version X SHOULD support minor | minor | |||
versions zero through X-1 as well. | versions zero through X-1 as well. | |||
</t> | </li> | |||
<li> | ||||
<t> | <t> | |||
Except for infrastructural changes, a minor version must not | Except for infrastructural changes, a minor version must not | |||
introduce REQUIRED new features. | introduce <bcp14>REQUIRED</bcp14> new features. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
This rule allows for the introduction of new functionality and forces | This rule allows for the introduction of new functionality and forces | |||
the use of implementation experience before designating a feature as | the use of implementation experience before designating a feature as | |||
REQUIRED. On the other hand, some classes of features are | <bcp14>REQUIRED</bcp14>. On the other hand, some classes of features are | |||
infrastructural and have broad effects. Allowing infrastructural features | infrastructural and have broad effects. Allowing infrastructural features | |||
to be RECOMMENDED or OPTIONAL complicates implementation of the minor version. | to be <bcp14>RECOMMENDED</bcp14> or <bcp14>OPTIONAL</bcp14> complicates impleme | |||
</t> | ntation of the minor version. | |||
</t> | ||||
<t> | </li> | |||
A client MUST NOT attempt to use a stateid, filehandle, or similar | <li> | |||
A client <bcp14>MUST NOT</bcp14> attempt to use a stateid, filehandle, or simil | ||||
ar | ||||
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. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | </section> | |||
</section> <!-- Minor Versioning --> | ||||
<section anchor="Non-RPC-based_Security_Services" title="Non-RPC-Based Security | <section anchor="Non-RPC-based_Security_Services" numbered="true" toc="default" | |||
Services"> | > | |||
<t> | <name>Non-RPC-Based Security Services</name> | |||
As described in | <t> | |||
<xref target="Authentication_Integrity_Privacy" />, | As described in <xref target="Authentication_Integrity_Privacy" format="defaul | |||
t"/>, | ||||
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> | |||
<section anchor="Authorization" numbered="true" toc="default"> | ||||
<section anchor="Authorization" title="Authorization"> | <name>Authorization</name> | |||
<t> | <t> | |||
Authorization to access a file object via an NFSv4.1 | Authorization to access a file object via an NFSv4.1 | |||
operation is ultimately determined by the NFSv4.1 | operation is ultimately determined by the NFSv4.1 | |||
server. A client can predetermine its access to a file | server. A client can predetermine its access to a file | |||
object via the OPEN (<xref target="OP_OPEN" />) | object via the OPEN (<xref target="OP_OPEN" format="default"/>) | |||
and the ACCESS (<xref target="OP_ACCESS" />) | and the ACCESS (<xref target="OP_ACCESS" format="default"/>) | |||
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" />) operation. Attributes that affect | (<xref target="OP_SETATTR" format="default"/>) operation. Attributes that af fect | |||
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" />. | sacl. See <xref target="file_attributes" format="default"/>. | |||
</t> | </t> | |||
</section> <!-- Authorization --> | </section> | |||
<section anchor="Auditing" title="Auditing"> | <section anchor="Auditing" numbered="true" toc="default"> | |||
<t> | <name>Auditing</name> | |||
<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" />. It is | and sacl attributes as described in <xref target="acl" format="default"/>. I t 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> <!-- Auditing --> | </section> | |||
<section anchor="Intrusion_Detection" title="Intrusion Detection"> | <section anchor="Intrusion_Detection" numbered="true" toc="default"> | |||
<t> | <name>Intrusion Detection</name> | |||
<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" />. | 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> <!-- Intrusion Detection --> | </section> | |||
</section> <!-- Non-RPC-based Security Services --> | </section> | |||
<section anchor="Transport_Layers" title="Transport Layers"> | ||||
<section anchor="Required_and_Recommended_Transport_Attributes" | <section anchor="Transport_Layers" numbered="true" toc="default"> | |||
title="REQUIRED and RECOMMENDED Properties of Transports"> | <name>Transport Layers</name> | |||
<t> | <section anchor="Required_and_Recommended_Transport_Attributes" numbered | |||
="true" toc="default"> | ||||
<name><bcp14>REQUIRED</bcp14> and <bcp14>RECOMMENDED</bcp14> Propertie | ||||
s of Transports</name> | ||||
<t> | ||||
NFSv4.1 works over Remote Direct Memory Access (RDMA) and non-RDMA-based tran sports with | NFSv4.1 works over Remote Direct Memory Access (RDMA) and non-RDMA-based tran sports with | |||
the following attributes: | the following attributes: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The transport supports reliable delivery of data, which | The transport supports reliable delivery of data, which | |||
NFSv4.1 requires but neither NFSv4.1 nor RPC has facilities | NFSv4.1 requires but neither NFSv4.1 nor RPC has facilities | |||
for ensuring <xref target="Chet" />. | for ensuring <xref target="Chet" format="default"/>. | |||
</t> | </li> | |||
<t> | <li> | |||
The transport delivers data in the order it was sent. | The transport delivers data in the order it was sent. | |||
Ordered delivery simplifies detection of transmit | Ordered delivery simplifies detection of transmit | |||
errors, and simplifies the sending of arbitrary sized | errors, and simplifies the sending of arbitrary sized | |||
requests and responses via the record marking | requests and responses via the record marking | |||
protocol <xref target="RFC5531" />. | protocol <xref target="RFC5531" format="default"/>. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Where an NFSv4.1 implementation supports operation | Where an NFSv4.1 implementation supports operation | |||
over the IP network protocol, any transport used between | over the IP network protocol, any transport used between | |||
NFS and IP MUST be among the IETF-approved congestion | NFS and IP <bcp14>MUST</bcp14> be among the IETF-approved congestion | |||
control transport protocols. At the time this document | control transport protocols. At the time this document | |||
was written, the only two transports that had the above | was written, the only two transports that had the above | |||
attributes were TCP and the Stream | attributes were TCP and the Stream | |||
Control Transmission Protocol (SCTP). To enhance the | Control Transmission Protocol (SCTP). To enhance the | |||
possibilities for interoperability, an NFSv4.1 | possibilities for interoperability, an NFSv4.1 | |||
implementation MUST support operation over the TCP | implementation <bcp14>MUST</bcp14> support operation over the TCP | |||
transport protocol. | transport protocol. | |||
</t> | </t> | |||
<t> | <t> | |||
Even if NFSv4.1 is used over a non-IP network | Even if NFSv4.1 is used over a non-IP network | |||
protocol, it is RECOMMENDED that the transport support | protocol, it is <bcp14>RECOMMENDED</bcp14> that the transport support | |||
congestion control. | congestion control. | |||
</t> | </t> | |||
<t> | <t> | |||
It is permissible for a connectionless transport to | It is permissible for a connectionless transport to | |||
be used under NFSv4.1; however, reliable and in-order | be used under NFSv4.1; however, reliable and in-order | |||
delivery of data combined with congestion control | delivery of data combined with congestion control | |||
by the connectionless transport is | by the connectionless transport is | |||
REQUIRED. As a consequence, UDP by itself MUST NOT be used | <bcp14>REQUIRED</bcp14>. As a consequence, UDP by itself <bcp14>MUST NOT</bc p14> 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> <!-- Required and Recommended Transport Attributes --> | </section> | |||
<section anchor="Client_and_Server_Transport_Behavior" title="Client and Serve | <section anchor="Client_and_Server_Transport_Behavior" numbered="true" toc="de | |||
r Transport Behavior"> | fault"> | |||
<t> | <name>Client and Server Transport Behavior</name> | |||
<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 SHOULD 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: | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
This will prevent the weakening of the transport's | This will prevent the weakening of the transport's | |||
congestion control mechanisms via short-lived | congestion control mechanisms via short-lived | |||
connections. | connections. | |||
</t> | </li> | |||
<t> | <li> | |||
This will improve performance for the WAN environment | This will improve performance for the WAN environment | |||
by eliminating the need for connection setup | by eliminating the need for connection setup | |||
handshakes. | handshakes. | |||
</t> | </li> | |||
<t> | <li> | |||
The NFSv4.1 callback model differs from NFSv4.0, and | The NFSv4.1 callback model differs from NFSv4.0, and | |||
requires the client and server to maintain a | requires the client and server to maintain a | |||
client-created backchannel (see <xref target="conn_chann_assoc" />) for the | client-created backchannel (see <xref target="conn_chann_assoc" format="defa | |||
server to use. | ult"/>) for the server to use. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | <t> | |||
<t> | ||||
In order to reduce congestion, if a connection-oriented | In order to reduce congestion, if a connection-oriented | |||
transport is used, and the request is not the NULL | transport is used, and the request is not the NULL | |||
procedure: | procedure: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
A requester MUST | <li> | |||
NOT retry a request unless the connection the request | A requester <bcp14>MUST NOT</bcp14> retry a request unless the connection th | |||
e request | ||||
was sent over was lost before the reply was | was sent over was lost before the reply was | |||
received. | received. | |||
</t> | </li> | |||
<t> | <li> | |||
A replier MUST | A replier <bcp14>MUST | |||
NOT silently drop a request, even if the request is a | NOT</bcp14> silently drop a request, even if the request is a | |||
retry. (The silent drop behavior of RPCSEC_GSS | retry. (The silent drop behavior of RPCSEC_GSS | |||
<xref target="RFC2203" /> does not apply | <xref target="RFC2203" format="default"/> does not apply | |||
because this behavior happens at the RPCSEC_GSS layer, | because this behavior happens at the RPCSEC_GSS layer, | |||
a lower layer in the request processing.) Instead, the | a lower layer in the request processing.) Instead, the | |||
replier SHOULD return an appropriate error (see | replier <bcp14>SHOULD</bcp14> return an appropriate error (see | |||
<xref target="Slot_Identifiers_and_Server_Reply_Cache" />), | <xref target="Slot_Identifiers_and_Server_Reply_Cache" format="default"/>), | |||
or it MAY disconnect the connection. | or it <bcp14>MAY</bcp14> disconnect the connection. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
When sending a reply, the replier MUST send the reply | When sending a reply, the replier <bcp14>MUST</bcp14> send the reply | |||
to the same full network address (e.g., if using an | to the same full network address (e.g., if using an | |||
IP-based transport, the source port of the requester | IP-based transport, the source port of the requester | |||
is part of the full network address) from which the requester | is part of the full network address) from which the requester | |||
sent the request. If using a connection-oriented | sent the request. If using a connection-oriented | |||
transport, replies MUST be sent on the same connection from which | transport, replies <bcp14>MUST</bcp14> be sent on the same connection from w hich | |||
the request was received. | the request was received. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
If a connection is dropped after the replier receives | If a connection is dropped after the replier receives | |||
the request but before the replier sends the reply, the | the request but before the replier sends the reply, the | |||
replier might have a pending reply. | replier might have a pending reply. | |||
If a connection is established with the same | If a connection is established with the same | |||
source and destination full network address as the | source and destination full network address as the | |||
dropped connection, then the replier MUST NOT send | dropped connection, then the replier <bcp14>MUST NOT</bcp14> send | |||
the reply until the requester retries the request. The | the reply until the requester retries the request. The | |||
reason for this prohibition is that the requester MAY | reason for this prohibition is that the requester <bcp14>MAY</bcp14> | |||
retry a request over a different connection (provided that connection | retry a request over a different connection (provided that connection | |||
is associated with the original request's session). | is associated with the original request's session). | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
When using RDMA transports, there are other reasons for not | When using RDMA transports, there are other reasons for not | |||
tolerating retries over the same connection: | tolerating retries over the same connection: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
RDMA transports use "credits" to enforce flow control, where | RDMA transports use "credits" to enforce flow control, where | |||
a credit is a right to a peer to transmit a message. | a credit is a right to a peer to transmit a message. | |||
If one peer were to retransmit a request (or reply), it would | If one peer were to retransmit a request (or reply), it would | |||
consume an additional credit. | consume an additional credit. | |||
If the replier | If the replier | |||
retransmitted a reply, it would certainly result in an RDMA | retransmitted a reply, it would certainly result in an RDMA | |||
connection loss, since the requester would typically only post a | connection loss, since the requester would typically only post a | |||
single receive buffer for each request. If the requester | single receive buffer for each request. If the requester | |||
retransmitted a request, the additional credit consumed on the | retransmitted a request, the additional credit consumed on the | |||
server might lead to RDMA connection failure unless the client | server might lead to RDMA connection failure unless the client | |||
accounted for it and decreased its available credit, leading to | accounted for it and decreased its available credit, leading to | |||
wasted resources. | wasted resources. | |||
</t> | </li> | |||
<t> | <li> | |||
RDMA credits present a new issue to the reply cache in | RDMA credits present a new issue to the reply cache in | |||
NFSv4.1. The reply cache may be used when a connection within a | NFSv4.1. The reply cache may be used when a connection within a | |||
session is lost, such as after the client reconnects. Credit | session is lost, such as after the client reconnects. Credit | |||
information is a dynamic property of the RDMA connection, and stale | information is a dynamic property of the RDMA connection, and stale | |||
values must not be replayed from the cache. This implies that the | values must not be replayed from the cache. This implies that the | |||
reply cache contents must not be blindly used when replies are | reply cache contents must not be blindly used when replies are | |||
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. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
In addition, as described in | In addition, as described in | |||
<xref target="Retry_and_Replay" />, while a session is active, | <xref target="Retry_and_Replay" format="default"/>, while a session is active | |||
the NFSv4.1 requester MUST NOT stop waiting for a reply. | , | |||
</t> | the NFSv4.1 requester <bcp14>MUST NOT</bcp14> stop waiting for a reply. | |||
</section> <!-- Client and Server Transport Behavior --> | </t> | |||
</section> | ||||
<section anchor="Ports" title="Ports"> | <section anchor="Ports" numbered="true" toc="default"> | |||
<t> | <name>Ports</name> | |||
<t> | ||||
Historically, NFSv3 servers have listened over | Historically, NFSv3 servers have listened over | |||
TCP port 2049. The registered port 2049 <xref target="RFC3232"/> | TCP port 2049. The registered port 2049 <xref target="RFC3232" format="defau lt"/> | |||
for the NFS protocol should be the default configuration. NFSv4.1 | for the NFS protocol should be the default configuration. NFSv4.1 | |||
clients SHOULD NOT use the RPC binding protocols as described in | clients <bcp14>SHOULD NOT</bcp14> use the RPC binding protocols as described | |||
<xref target="RFC1833"/>. | in | |||
</t> | <xref target="RFC1833" format="default"/>. | |||
</section> <!-- Ports --> | </t> | |||
</section> | ||||
</section> <!-- Transport Layers --> | </section> | |||
<section anchor="Session" title="Session"> | <section anchor="Session" numbered="true" toc="default"> | |||
<t> | <name>Session</name> | |||
NFSv4.1 clients and servers MUST support and MUST use the session | <t> | |||
NFSv4.1 clients and servers <bcp14>MUST</bcp14> support and <bcp14>MUST</bcp1 | ||||
4> 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" title="Motivation and Overview"> | <name>Motivation and Overview</name> | |||
<t> | <t> | |||
Previous versions and minor versions of NFS have suffered from | Previous versions and minor versions of NFS have suffered from | |||
the following: | the following: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Lack of support for Exactly Once Semantics (EOS). This includes | Lack of support for Exactly Once Semantics (EOS). This includes | |||
lack of support for EOS through server failure and recovery. | lack of support for EOS through server failure and recovery. | |||
</t> | </li> | |||
<t> | <li> | |||
Limited callback support, including no support for sending callbacks | Limited callback support, including no support for sending callbacks | |||
through firewalls, and races between replies to normal requests | through firewalls, and races between replies to normal requests | |||
and callbacks. | and callbacks. | |||
</t> | </li> | |||
<t> | <li> | |||
Limited trunking over multiple network paths. | Limited trunking over multiple network paths. | |||
</t> | </li> | |||
<t> | <li> | |||
Requiring machine credentials for fully secure operation. | Requiring machine credentials for fully secure operation. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
Through the introduction of a session, NFSv4.1 addresses the | Through the introduction of a session, NFSv4.1 addresses the | |||
above shortfalls with practical solutions: | above shortfalls with practical solutions: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
EOS is enabled by a reply cache with a bounded size, | EOS is enabled by a reply cache with a bounded size, | |||
making it feasible to keep the cache in persistent storage and enable | making it feasible to keep the cache in persistent storage and enable | |||
EOS through server failure and recovery. One reason that | EOS through server failure and recovery. One reason that | |||
previous revisions of NFS did not support EOS was | previous revisions of NFS did not support EOS was | |||
because some EOS approaches often limited parallelism. | because some EOS approaches often limited parallelism. | |||
As will be explained in | As will be explained in | |||
<xref target="Exactly_Once_Semantics" />, | <xref target="Exactly_Once_Semantics" format="default"/>, | |||
NFSv4.1 supports both EOS and unlimited parallelism. | NFSv4.1 supports both EOS and unlimited parallelism. | |||
</t> | </li> | |||
<t> | <li> | |||
The NFSv4.1 client (defined in <xref target="intro_definitions" />, | The NFSv4.1 client (defined in <xref target="client_def" format="default"/>) | |||
<xref target="client_def"/>) creates transport | creates transport | |||
connections and provides them to the server to use for sending | connections and provides them to the server to use for sending | |||
callback requests, thus solving the firewall issue | callback requests, thus solving the firewall issue | |||
(<xref target="OP_BIND_CONN_TO_SESSION" />). Races between | (<xref target="OP_BIND_CONN_TO_SESSION" format="default"/>). Races between | |||
responses from client requests and callbacks caused by | responses from client requests and callbacks caused by | |||
the requests are detected via the session's sequencing | the requests are detected via the session's sequencing | |||
properties that are a consequence of EOS | properties that are a consequence of EOS | |||
(<xref target="sessions_callback_races" />). | (<xref target="sessions_callback_races" format="default"/>). | |||
</t> | </li> | |||
<t> | <li> | |||
The NFSv4.1 client can associate an arbitrary number of connections with | The NFSv4.1 client can associate an arbitrary number of connections with | |||
the session, and thus provide trunking (<xref target="Trunking" />). | the session, and thus provide trunking (<xref target="Trunking" format="defa | |||
</t> | ult"/>). | |||
<t> | </li> | |||
<li> | ||||
The NFSv4.1 client and server produce a session key independent of client | The NFSv4.1 client and server produce a session key independent of client | |||
and server machine credentials which can be | and server machine credentials which can be | |||
used to compute a digest for protecting critical session management operatio ns | used to compute a digest for protecting critical session management operatio ns | |||
(<xref target="protect_state_change" />). | (<xref target="protect_state_change" format="default"/>). | |||
</t> | </li> | |||
<t> | <li> | |||
The NFSv4.1 client can also create secure RPCSEC_GSS contexts | The NFSv4.1 client can also create secure RPCSEC_GSS contexts | |||
for use by the session's backchannel that do not require | for use by the session's backchannel that do not require | |||
the server to authenticate to a client machine principal | the server to authenticate to a client machine principal | |||
(<xref target="Backchannel_RPC_Security" />). | (<xref target="Backchannel_RPC_Security" format="default"/>). | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
A session is a dynamically created, long-lived server object | A session is a dynamically created, long-lived server object | |||
created by a client and used over time from one or more transport | created by a client and used over time from one or more transport | |||
connections. Its function is to maintain the server's state | connections. Its function is to maintain the server's state | |||
relative to the connection(s) belonging to a client instance. This | relative to the connection(s) belonging to a client instance. This | |||
state is entirely independent of the connection itself, and indeed | state is entirely independent of the connection itself, and indeed | |||
the state exists whether or not the connection exists. A client may | the state exists whether or not the connection exists. A client may | |||
have one or more sessions associated with it so that | have one or more sessions associated with it so that | |||
client-associated state may be accessed using any of the sessions | client-associated state may be accessed using any of the sessions | |||
associated with that client's client ID, when connections are | associated with that client's client ID, when connections are | |||
associated with those sessions. When no connections are associated | associated with those sessions. When no connections are associated | |||
with any of a client ID's sessions for an extended time, such | with any of a client ID's sessions for an extended time, such | |||
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 MUST | A single client may create multiple sessions. A single session <bcp14>MUST | |||
NOT serve multiple clients. | NOT</bcp14> serve multiple clients. | |||
</t> | </t> | |||
</section> <!-- Motivation and Overview --> | </section> | |||
<section anchor="NFSv4_Integration" title="NFSv4 Integration"> | <section anchor="NFSv4_Integration" numbered="true" toc="default"> | |||
<t> | <name>NFSv4 Integration</name> | |||
<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 proced ure, COMPOUND, | NFS. However, because NFSv4 encapsulates its functionality in a single proced ure, 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. COMPO UND includes | operations, sessions have been added to NFSv4.1 with little difficulty. COMPO UND includes | |||
a minor version number field, and for NFSv4.1 this minor version | a minor version number field, and for NFSv4.1 this minor version | |||
is set to 1. When the NFSv4 server processes a COMPOUND with | is set to 1. When the NFSv4 server processes a COMPOUND with | |||
the minor version set to 1, it expects a different set of | the minor version set to 1, it expects a different set of | |||
operations than it does for NFSv4.0. NFSv4.1 defines the | operations than it does for NFSv4.0. NFSv4.1 defines the | |||
SEQUENCE operation, which is required for every | SEQUENCE operation, which is required for every | |||
COMPOUND that operates over an established session, with the | COMPOUND that operates over an established session, with the | |||
exception of some session administration operations, such | exception of some session administration operations, such | |||
as DESTROY_SESSION (<xref target="OP_DESTROY_SESSION" />). | as DESTROY_SESSION (<xref target="OP_DESTROY_SESSION" format="default"/>). | |||
</t> | </t> | |||
<section anchor="SEQUENCE_and_CB_SEQUENCE" numbered="true" toc="defaul | ||||
<section anchor="SEQUENCE_and_CB_SEQUENCE" title="SEQUENCE and CB_SEQUENCE"> | t"> | |||
<t> | <name>SEQUENCE and CB_SEQUENCE</name> | |||
In NFSv4.1, when the SEQUENCE operation is present, it MUST be | <t> | |||
In NFSv4.1, when the SEQUENCE operation is present, it <bcp14>MUST</bcp14> | ||||
be | ||||
the first operation in the COMPOUND procedure. The primary purpose | the first operation in the COMPOUND procedure. The primary purpose | |||
of SEQUENCE is to carry the session identifier. The session identifier | of SEQUENCE is to carry the session identifier. The session identifier | |||
associates all other operations in the COMPOUND procedure with | associates all other operations in the COMPOUND procedure with | |||
a particular session. SEQUENCE also contains required information | a particular session. SEQUENCE also contains required information | |||
for maintaining EOS (see <xref target="Exactly_Once_Semantics" />). | for maintaining EOS (see <xref target="Exactly_Once_Semantics" format="defa ult"/>). | |||
Session-enabled NFSv4.1 COMPOUND requests thus have the form: | Session-enabled NFSv4.1 COMPOUND requests thus have the form: | |||
</t> | </t> | |||
<figure> | <artwork name="" type="" align="left" alt=""><![CDATA[ | |||
<artwork> | ||||
+-----+--------------+-----------+------------+-----------+---- | +-----+--------------+-----------+------------+-----------+---- | |||
| tag | minorversion | numops |SEQUENCE op | op + args | ... | | tag | minorversion | numops |SEQUENCE op | op + args | ... | |||
| | (== 1) | (limited) | + args | | | | | (== 1) | (limited) | + args | | | |||
+-----+--------------+-----------+------------+-----------+---- | +-----+--------------+-----------+------------+-----------+---- | |||
</artwork> | ]]></artwork> | |||
</figure> | <t> | |||
<t> | ||||
and the replies have the form: | and the replies have the form: | |||
</t> | </t> | |||
<artwork name="" type="" align="left" alt=""><![CDATA[ | ||||
<figure> | ||||
<artwork> | ||||
+------------+-----+--------+-------------------------------+--// | +------------+-----+--------+-------------------------------+--// | |||
|last status | tag | numres |status + SEQUENCE op + results | // | |last status | tag | numres |status + SEQUENCE op + results | // | |||
+------------+-----+--------+-------------------------------+--// | +------------+-----+--------+-------------------------------+--// | |||
//-----------------------+---- | //-----------------------+---- | |||
// status + op + results | ... | // status + op + results | ... | |||
//-----------------------+---- | //-----------------------+---- | |||
</artwork> | ]]></artwork> | |||
</figure> | <t> | |||
<t> | ||||
A CB_COMPOUND procedure request and reply has a similar form to | A CB_COMPOUND procedure request and reply has a similar form to | |||
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 MUST 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" />). | (<xref target="sessions_callback_races" format="default"/>). | |||
</t> | </t> | |||
</section> <!-- SEQUENCE and CB_SEQUENCE --> | </section> | |||
<section anchor="Client_ID_and_Session_Association" | <section anchor="Client_ID_and_Session_Association" numbered="true" toc="defa | |||
title="Client ID and Session Association"> | ult"> | |||
<t> | <name>Client ID and Session Association</name> | |||
Each client ID (<xref target="Client_Identifiers" />) can have | <t> | |||
Each client ID (<xref target="Client_Identifiers" format="default"/>) can ha | ||||
ve | ||||
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 | |||
client ID is automatically renewed. | client ID is automatically renewed. | |||
</t> | </t> | |||
<t> | <t> | |||
State (which can consist of share reservations, locks, delegations, | State (which can consist of share reservations, locks, delegations, | |||
and layouts (<xref target="intro_locking" />)) is tied to | and layouts (<xref target="intro_locking" format="default"/>)) is tied to | |||
the client ID. Client state is not tied to any individual session. | the client ID. Client state is not tied to any individual session. | |||
Successive state changing operations from a given state | Successive state changing operations from a given state | |||
owner MAY go over different sessions, provided the | owner <bcp14>MAY</bcp14> go over different sessions, provided the | |||
session is associated with the same client ID. A callback | session is associated with the same client ID. A callback | |||
MAY arrive over a different session than that of the request | <bcp14>MAY</bcp14> arrive over a different session than that of the request | |||
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 MAY 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> <!-- Client ID and Session Association --> | </section> | |||
</section> <!-- NFSv4 Integration --> | ||||
<section anchor="Channels" title="Channels"> | <section anchor="Channels" numbered="true" toc="default"> | |||
<t> | <name>Channels</name> | |||
<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 | |||
channel has a distinct purpose, channels are not assigned | channel has a distinct purpose, channels are not assigned | |||
identifiers. | identifiers. | |||
</t> | </t> | |||
<t> | <t> | |||
The fore channel is | The fore channel is | |||
used for ordinary requests from the client to the server, and | used for ordinary requests from the client to the server, and | |||
carries COMPOUND requests and responses. | carries COMPOUND requests and responses. | |||
A session always has a fore channel. | A session always has a fore channel. | |||
</t> | </t> | |||
<t> | <t> | |||
The backchannel is used for callback requests from server | The backchannel is used for callback requests from server | |||
to client, and carries CB_COMPOUND requests and responses. | to client, and carries CB_COMPOUND requests and responses. | |||
Whether or not there is a backchannel is decided by the | Whether or not there is a backchannel is decided by the | |||
client; however, many features of NFSv4.1 require a backchannel. | client; however, many features of NFSv4.1 require a backchannel. | |||
NFSv4.1 servers MUST support backchannels. | NFSv4.1 servers <bcp14>MUST</bcp14> support backchannels. | |||
</t> | </t> | |||
<t> | <t> | |||
Each session has resources for each channel, | Each session has resources for each channel, | |||
including separate reply caches (see | including separate reply caches (see | |||
<xref target="Slot_Identifiers_and_Server_Reply_Cache" />). | <xref target="Slot_Identifiers_and_Server_Reply_Cache" format="default"/>). | |||
Note that even the backchannel requires a reply cache (or, at least, | Note that even the backchannel requires a reply cache (or, at least, | |||
a slot table in order to detect retries) because | a slot table in order to detect retries) because | |||
some callback operations are nonidempotent. | some callback operations are non-idempotent. | |||
</t> | </t> | |||
<section anchor="conn_chann_assoc" numbered="true" toc="default"> | ||||
<section anchor="conn_chann_assoc" title="Association of Connections, Channel | <name>Association of Connections, Channels, and Sessions</name> | |||
s, and Sessions"> | <t> | |||
<t> | ||||
Each channel is associated with zero or more transport | Each channel is associated with zero or more transport | |||
connections (whether of the same transport protocol or different | connections (whether of the same transport protocol or different | |||
transport protocols). A connection can be associated with | transport protocols). A connection can be associated with | |||
one channel or both channels of a session; the client | one channel or both channels of a session; the client | |||
and server negotiate whether a connection will carry | and server negotiate whether a connection will carry | |||
traffic for one channel or both channels via the | traffic for one channel or both channels via the | |||
CREATE_SESSION (<xref target="OP_CREATE_SESSION" | CREATE_SESSION (<xref target="OP_CREATE_SESSION" format="default"/>) and the | |||
/>) and the BIND_CONN_TO_SESSION (<xref | BIND_CONN_TO_SESSION (<xref target="OP_BIND_CONN_TO_SESSION" format="default"/> | |||
target="OP_BIND_CONN_TO_SESSION" />) operations. When a | ) operations. When a | |||
session is created via CREATE_SESSION, the connection | session is created via CREATE_SESSION, the connection | |||
that transported the CREATE_SESSION request is | that transported the CREATE_SESSION request is | |||
automatically associated with the fore channel, and | automatically associated with the fore channel, and | |||
optionally the backchannel. If the client specifies no | optionally the backchannel. If the client specifies no | |||
state protection (<xref target="OP_EXCHANGE_ID" />) | state protection (<xref target="OP_EXCHANGE_ID" format="default"/>) | |||
when the session is created, then when SEQUENCE is | when the session is created, then when SEQUENCE is | |||
transmitted on a different connection, the connection | transmitted on a different connection, the connection | |||
is automatically associated with the fore channel of | is automatically associated with the fore channel of | |||
the session specified in the SEQUENCE operation. | the session specified in the SEQUENCE operation. | |||
</t> | </t> | |||
<t> | <t> | |||
A connection's association with a session is | A connection's association with a session is | |||
not exclusive. A connection associated with the channel(s) | not exclusive. A connection associated with the channel(s) | |||
of one session may be simultaneously | of one session may be simultaneously | |||
associated with the channel(s) of other sessions including | associated with the channel(s) of other sessions including | |||
sessions associated with other client IDs. | sessions associated with other client IDs. | |||
</t> | </t> | |||
<t> | <t> | |||
It is permissible for connections of multiple transport | It is permissible for connections of multiple transport | |||
types to be associated with the same channel. For | types to be associated with the same channel. For | |||
example, both TCP and RDMA connections can be | example, both TCP and RDMA connections can be | |||
associated with the fore channel. In the event an | associated with the fore channel. In the event an | |||
RDMA and non-RDMA connection are associated with the | RDMA and non-RDMA connection are associated with the | |||
same channel, the maximum number of slots SHOULD be | same channel, the maximum number of slots <bcp14>SHOULD</bcp14> be | |||
at least one more than the total number of RDMA credits | at least one more than the total number of RDMA credits | |||
(<xref target="Slot_Identifiers_and_Server_Reply_Cache" />). | (<xref target="Slot_Identifiers_and_Server_Reply_Cache" format="default"/>). | |||
This way, if all RDMA credits are used, the non-RDMA | This way, if all RDMA credits are used, the non-RDMA | |||
connection can have at least one outstanding request. | connection can have at least one outstanding request. | |||
If a server supports multiple transport types, it MUST | If a server supports multiple transport types, it <bcp14>MUST</bcp14> | |||
allow a client to associate connections from each transport | allow a client to associate connections from each transport | |||
to a channel. | to a channel. | |||
</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> <!-- Channels --> | </section> | |||
<section title="Server Scope" | <section anchor="Server_Scope" numbered="true" toc="default"> | |||
anchor="Server_Scope"> | <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 | |||
assign the same value to two distinct objects. Thus, the identifiers | assign the same value to two distinct objects. Thus, the identifiers | |||
generated by two servers within that set can be assumed compatible | generated by two servers within that set can be assumed compatible | |||
so that, in certain important cases, | so that, in certain important cases, | |||
identifiers generated by one server in that set may be | identifiers generated by one server in that set may be | |||
presented to | presented to | |||
another server of the same scope. | another server of the same scope. | |||
</t> | </t> | |||
<t> | <t> | |||
The use of such compatible values does not imply that | The use of such compatible values does not imply that | |||
a value generated by one server will always be accepted | a value generated by one server will always be accepted | |||
by another. In most cases, it will not. However, a | by another. In most cases, it will not. However, a | |||
server will not inadvertently accept a value generated by another | server will not inadvertently accept a value generated by another | |||
server. When it does accept it, it will be because | server. When it does accept it, it will be because | |||
it is recognized as valid and carrying the same meaning | it is recognized as valid and carrying the same meaning | |||
as on another server of the same scope. | as on another server of the same scope. | |||
</t> | </t> | |||
<t> | <t> | |||
When servers are of the same server scope, this compatibility | When servers are of the same server scope, this compatibility | |||
of values applies to the following identifiers: | of values applies to the following identifiers: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Filehandle values. A filehandle value accepted by two | Filehandle values. A filehandle value accepted by two | |||
servers of the same server scope denotes the same object. | servers of the same server scope denotes the same object. | |||
A WRITE operation sent to one server is reflected immediately | A WRITE operation sent to one server is reflected immediately | |||
in a READ sent to the other. | in a READ sent to the other. | |||
</t> | </li> | |||
<t> | <li> | |||
Server owner values. When the server scope values are | Server owner values. When the server scope values are | |||
the same, server owner value may be validly compared. | the same, server owner value may be validly compared. | |||
In cases where the server scope values are different, server | In cases where the server scope values are different, server | |||
owner values are treated as different even if they | owner values are treated as different even if they | |||
contain identical strings of bytes. | contain identical strings of bytes. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The coordination among servers required to provide such | The coordination among servers required to provide such | |||
compatibility can be quite minimal, and limited to a simple | compatibility can be quite minimal, and limited to a simple | |||
partition of the ID space. The recognition of common values | partition of the ID space. The recognition of common values | |||
requires additional implementation, but this can be tailored | requires additional implementation, but this can be tailored | |||
to the specific situations in which that recognition is | to the specific situations in which that recognition is | |||
desired. | desired. | |||
</t> | </t> | |||
<t> | <t> | |||
Clients will have occasion to compare the server scope values | Clients will have occasion to compare the server scope values | |||
of multiple servers under a number of circumstances, each of | of multiple servers under a number of circumstances, each of | |||
which will be discussed under the appropriate functional | which will be discussed under the appropriate functional | |||
section: | section: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
When server owner values received in response to | When server owner values received in response to | |||
EXCHANGE_ID operations sent to multiple network | EXCHANGE_ID operations sent to multiple network | |||
addresses are compared for the purpose of determining | addresses are compared for the purpose of determining | |||
the validity of various forms of trunking, as described | the validity of various forms of trunking, as described | |||
in <xref target="SEC11-USES-trunk" />. . | in <xref target="SEC11-USES-trunk" format="default"/>. | |||
</t> | </li> | |||
<t> | <li> | |||
When network or server reconfiguration causes the same | When network or server reconfiguration causes the same | |||
network address to possibly be directed to different | network address to possibly be directed to different | |||
servers, with the necessity for the client to determine | servers, with the necessity for the client to determine | |||
when lock reclaim should be attempted, as described | when lock reclaim should be attempted, as described | |||
in <xref target="reclaim_locks" />. | in <xref target="reclaim_locks" format="default"/>. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
When two replies from EXCHANGE_ID, each from two different | When two replies from EXCHANGE_ID, each from two different | |||
server network addresses, have the same server scope, there | server network addresses, have the same server scope, there | |||
are a number of ways a client can validate that the common | are a number of ways a client can validate that the common | |||
server scope is due to two servers cooperating in a group. | server scope is due to two servers cooperating in a group. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If both EXCHANGE_ID requests were sent with RPCSEC_GSS | If both EXCHANGE_ID requests were sent with RPCSEC_GSS | |||
(<xref target="RFC2203"/>, <xref target="RFC5403"/>, | (<xref target="RFC2203" format="default"/>, <xref target="RFC5403" format | |||
<xref target="RFC7861"/>) | ="default"/>, | |||
<xref target="RFC7861" format="default"/>) | ||||
authentication and the server principal is the same for | authentication and the server principal is the same for | |||
both targets, the equality of server scope is validated. | both targets, the equality of server scope is validated. | |||
It is RECOMMENDED that two servers intending to share the | It is <bcp14>RECOMMENDED</bcp14> that two servers intending to share the | |||
same server scope and server_owner major_id also share the | same server scope and server_owner major_id also share the | |||
same principal name. In some cases, this | same principal name. In some cases, this | |||
simplifies the client's task of validating server scope. | simplifies the client's task of validating server scope. | |||
</t> | </li> | |||
<t> | <li> | |||
The client may accept the appearance of the second | The client may accept the appearance of the second | |||
server in the fs_locations or fs_locations_info attribute | server in the fs_locations or fs_locations_info attribute | |||
for a relevant file system. For example, if there is | for a relevant file system. For example, if there is | |||
a migration event for a particular file system | a migration event for a particular file system | |||
or there are locks to be reclaimed on a particular file | or there are locks to be reclaimed on a particular file | |||
system, the attributes for that particular file system | system, the attributes for that particular file system | |||
may be used. The client sends the GETATTR request to | may be used. The client sends the GETATTR request to | |||
the first server for the fs_locations or | the first server for the fs_locations or | |||
fs_locations_info attribute with RPCSEC_GSS | fs_locations_info attribute with RPCSEC_GSS | |||
authentication. It may need to do this in advance | authentication. It may need to do this in advance | |||
of the need to verify the common server scope. | of the need to verify the common server scope. | |||
If the client successfully authenticates the reply | If the client successfully authenticates the reply | |||
to GETATTR, and the GETATTR request and reply containing | to GETATTR, and the GETATTR request and reply containing | |||
the fs_locations or fs_locations_info attribute refers | the fs_locations or fs_locations_info attribute refers | |||
to the second server, then the equality of server scope | to the second server, then the equality of server scope | |||
is supported. A client may choose to limit the use of | is supported. A client may choose to limit the use of | |||
this form of support to information relevant to the | this form of support to information relevant to the | |||
specific file system involved (e.g. a file system | specific file system involved (e.g. a file system | |||
being migrated). | being migrated). | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section anchor="Trunking" numbered="true" toc="default"> | |||
<section title="Trunking" | <name>Trunking</name> | |||
anchor="Trunking"> | <t> | |||
<t> | ||||
Trunking is the use of multiple connections between a | Trunking is the use of multiple connections between a | |||
client and server in order to increase the speed of data | client and server in order to increase the speed of data | |||
transfer. NFSv4.1 supports two types of trunking: | transfer. NFSv4.1 supports two types of trunking: | |||
session trunking and client ID trunking. | session trunking and client ID trunking. | |||
</t> | </t> | |||
<t> | <t> | |||
In the context of a single server network address, it | In the context of a single server network address, it | |||
can be assumed that all connections are accessing the | can be assumed that all connections are accessing the | |||
same server and NFSv4.1 | same server, and NFSv4.1 | |||
servers MUST support both forms of trunking. When | servers <bcp14>MUST</bcp14> support both forms of trunking. When | |||
multiple connections use a set of network addresses | multiple connections use a set of network addresses | |||
accessing the same server, the server | to access the same server, the server | |||
MUST support both forms of trunking. | <bcp14>MUST</bcp14> support both forms of trunking. | |||
NFSv4.1 servers in a clustered configuration MAY allow | NFSv4.1 servers in a clustered configuration <bcp14>MAY</bcp14> allow | |||
network addresses for different servers to use client ID | network addresses for different servers to use client ID | |||
trunking. | trunking. | |||
</t> | </t> | |||
<t> | <t> | |||
Clients may use either form of trunking as long as they | Clients may use either form of trunking as long as they | |||
do not, when trunking between different server network | do not, when trunking between different server network | |||
addresses, violate the servers' mandates as to the | addresses, violate the servers' mandates as to the | |||
kinds of trunking to be allowed (see below). With regard | kinds of trunking to be allowed (see below). With regard | |||
to callback channels, the client MUST allow the server to | to callback channels, the client <bcp14>MUST</bcp14> allow the server to | |||
choose among all callback channels valid for a given | choose among all callback channels valid for a given | |||
client ID and MUST support trunking when the connections | client ID and <bcp14>MUST</bcp14> support trunking when the connections | |||
supporting the backchannel allow session or client ID | supporting the backchannel allow session or client ID | |||
trunking to be used for callbacks. | trunking to be used for callbacks. | |||
</t> | </t> | |||
<t> | <t> | |||
Session trunking is essentially the association of multiple | Session trunking is essentially the association of multiple | |||
connections, each with potentially different target and/or source | connections, each with potentially different target and/or source | |||
network addresses, to the same session. When the target network | network addresses, to the same session. When the target network | |||
addresses (server addresses) of the two connections are the same, | addresses (server addresses) of the two connections are the same, | |||
the server MUST | the server <bcp14>MUST</bcp14> | |||
support such session trunking. When the target network addresses | support such session trunking. When the target network addresses | |||
are different, the server MAY indicate such support using the | are different, the server <bcp14>MAY</bcp14> indicate such support using th e | |||
data returned by the EXCHANGE_ID operation (see below). | data returned by the EXCHANGE_ID operation (see below). | |||
</t> | </t> | |||
<t> | <t> | |||
Client ID trunking is the association of multiple | Client ID trunking is the association of multiple | |||
sessions to the same client ID. Servers MUST support client ID | sessions to the same client ID. Servers <bcp14>MUST</bcp14> support client ID | |||
trunking for two target network addresses whenever they allow | trunking for two target network addresses whenever they allow | |||
session trunking for those same two network addresses. | session trunking for those same two network addresses. | |||
In addition, a server MAY, by presenting the same | In addition, a server <bcp14>MAY</bcp14>, by presenting the same | |||
major server owner ID | major server owner ID | |||
(<xref target="Server_Owners" />) and server scope | (<xref target="Server_Owners" format="default"/>) and server scope | |||
(<xref target="Server_Scope" />), allow an additional | (<xref target="Server_Scope" format="default"/>), allow an additional | |||
case of client ID trunking. When two | case of client ID trunking. When two | |||
servers return the same major server owner and server | servers return the same major server owner and server | |||
scope, it means that the two servers are cooperating on | scope, it means that the two servers are cooperating on | |||
locking state management, which is a prerequisite | locking state management, which is a prerequisite | |||
for client ID trunking. | for client ID trunking. | |||
</t> | </t> | |||
<t> | <t> | |||
Distinguishing when the client is allowed to use session and | Distinguishing when the client is allowed to use session and | |||
client ID trunking requires understanding how the results of the | client ID trunking requires understanding how the results of the | |||
EXCHANGE_ID (<xref target="OP_EXCHANGE_ID" />) | EXCHANGE_ID (<xref target="OP_EXCHANGE_ID" format="default"/>) | |||
operation identify a server. | operation identify a server. | |||
Suppose a client sends EXCHANGE_IDs over two different | Suppose a client sends EXCHANGE_IDs over two different | |||
connections, each with a possibly different target | connections, each with a possibly different target | |||
network address, but each EXCHANGE_ID operation has the same | network address, but each EXCHANGE_ID operation has the same | |||
value in the eia_clientowner field. If the same | value in the eia_clientowner field. If the same | |||
NFSv4.1 server is listening over each connection, | NFSv4.1 server is listening over each connection, | |||
then each EXCHANGE_ID result MUST return the same | then each EXCHANGE_ID result <bcp14>MUST</bcp14> return the same | |||
values of eir_clientid, eir_server_owner.so_major_id, | values of eir_clientid, eir_server_owner.so_major_id, | |||
and eir_server_scope. The client can then treat each | and eir_server_scope. The client can then treat each | |||
connection as referring to the same server (subject | connection as referring to the same server (subject | |||
to verification; see | to verification; see | |||
<xref target="PREP-trunk-verify" /> below), | <xref target="PREP-trunk-verify" format="default"/> below), | |||
and it can use each connection to trunk requests and | and it can use each connection to trunk requests and | |||
replies. | replies. | |||
The client's choice is whether session trunking | The client's choice is whether session trunking | |||
or client ID trunking applies. | or client ID trunking applies. | |||
<list style="hanging"> | </t> | |||
<dl newline="false" spacing="normal"> | ||||
<t hangText="Session Trunking."> | <dt>Session Trunking.</dt> | |||
<dd> | ||||
<t> | ||||
If the eia_clientowner argument is the same in | If the eia_clientowner argument is the same in | |||
two different EXCHANGE_ID requests, and | two different EXCHANGE_ID requests, and | |||
the eir_clientid, eir_server_owner.so_major_id, | the eir_clientid, eir_server_owner.so_major_id, | |||
eir_server_owner.so_minor_id, and eir_server_scope | eir_server_owner.so_minor_id, and eir_server_scope | |||
results match in both EXCHANGE_ID results, then | results match in both EXCHANGE_ID results, then | |||
the client is permitted to perform session trunking. | the client is permitted to perform session trunking. | |||
If the client has no session mapping to the tuple of | If the client has no session mapping to the tuple of | |||
eir_clientid, eir_server_owner.so_major_id, eir_server_scope, and | eir_clientid, eir_server_owner.so_major_id, eir_server_scope, and | |||
eir_server_owner.so_minor_id, then it creates | eir_server_owner.so_minor_id, then it creates | |||
the session via a CREATE_SESSION operation over one | the session via a CREATE_SESSION operation over one | |||
of the connections, which associates the connection | of the connections, which associates the connection | |||
to the session. If there is a session for the tuple, | to the session. If there is a session for the tuple, | |||
the client can send BIND_CONN_TO_SESSION to associate | the client can send BIND_CONN_TO_SESSION to associate | |||
the connection to the session. | the connection to the session. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
Of course, if the client | Of course, if the client | |||
does not desire to use session trunking, it is not | does not desire to use session trunking, it is not | |||
required to do so. It can invoke | required to do so. It can invoke | |||
CREATE_SESSION on the connection. This will result | CREATE_SESSION on the connection. This will result | |||
in client ID trunking as described below. It can also | in client ID trunking as described below. It can also | |||
decide to drop the connection if it does not choose to | decide to drop the connection if it does not choose to | |||
use trunking. | use trunking. | |||
<vspace blankLines='1' /> | </t> | |||
</dd> | ||||
</t> | <dt>Client ID Trunking.</dt> | |||
<dd> | ||||
<t hangText="Client ID Trunking."> | <t> | |||
If the eia_clientowner argument is the same in | If the eia_clientowner argument is the same in | |||
two different EXCHANGE_ID requests, and | two different EXCHANGE_ID requests, and | |||
the eir_clientid, eir_server_owner.so_major_id, | the eir_clientid, eir_server_owner.so_major_id, | |||
and eir_server_scope | and eir_server_scope | |||
results match in both EXCHANGE_ID results, then | results match in both EXCHANGE_ID results, then | |||
the client is permitted to perform client ID trunking | the client is permitted to perform client ID trunking | |||
(regardless of whether the eir_server_owner.so_minor_id results match). | (regardless of whether the eir_server_owner.so_minor_id results match). | |||
The client can associate | The client can associate | |||
each connection with different sessions, where | each connection with different sessions, where | |||
each session is associated with the same server. | each session is associated with the same server. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
The client completes the act of client ID trunking by invoking | The client completes the act of client ID trunking by invoking | |||
CREATE_SESSION on each connection, using the same | CREATE_SESSION on each connection, using the same | |||
client ID that was returned in eir_clientid. These | client ID that was returned in eir_clientid. These | |||
invocations create two sessions and also associate | invocations create two sessions and also associate | |||
each connection with its respective session. The client | each connection with its respective session. The client | |||
is free to decline to use client ID trunking by simply | is free to decline to use client ID trunking by simply | |||
dropping the connection at this point. | dropping the connection at this point. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
When doing client ID trunking, locking state | When doing client ID trunking, locking state | |||
is shared across sessions associated with that same | is shared across sessions associated with that same | |||
client ID. This requires the server to coordinate | client ID. This requires the server to coordinate | |||
state across sessions and the client to be able to | state across sessions and the client to be able to | |||
associate the same locking state with multiple sessions. | associate the same locking state with multiple sessions. | |||
</t> | ||||
</t> | </dd> | |||
</dl> | ||||
</list> | <t> | |||
</t> | ||||
<t> | ||||
It is always possible that, as a result of various sorts | It is always possible that, as a result of various sorts | |||
of reconfiguration events, eir_server_scope and | of reconfiguration events, eir_server_scope and | |||
eir_server_owner values may be different on subsequent | eir_server_owner values may be different on subsequent | |||
EXCHANGE_ID requests made to the same network address. | EXCHANGE_ID requests made to the same network address. | |||
</t> | </t> | |||
<t> | <t> | |||
In most cases such reconfiguration events will be | In most cases, such reconfiguration events will be | |||
disruptive and indicate that an IP address formerly connected | disruptive and indicate that an IP address formerly connected | |||
to one server is now connected to an entirely different one. | to one server is now connected to an entirely different one. | |||
</t> | </t> | |||
<t> | <t> | |||
Some guidelines on client handling of such situations follow: | Some guidelines on client handling of such situations follow: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
When eir_server_scope changes, the client has no assurance | When eir_server_scope changes, the client has no assurance | |||
that any id's it obtained previously (e.g. file handles) can | that any IDs that it obtained previously (e.g., filehandles) can | |||
be validly used on the new server, and, even if the new | be validly used on the new server, and, even if the new | |||
server accepts them, there is no assurance that this is not | server accepts them, there is no assurance that this is not | |||
due to accident. Thus, it is best to treat all such state | due to accident. Thus, it is best to treat all such state | |||
as lost/stale although a client may assume that the | as lost or stale, although a client may assume that the | |||
probability of inadvertent acceptance is low and treat | probability of inadvertent acceptance is low and treat | |||
this situation as within the next case. | this situation as within the next case. | |||
</t> | </li> | |||
<t> | <li> | |||
When eir_server_scope remains the same and | When eir_server_scope remains the same and | |||
eir_server_owner.so_major_id changes, the client can use | eir_server_owner.so_major_id changes, the client can use | |||
the filehandles it has, consider its locking state lost, | the filehandles it has, consider its locking state lost, | |||
and attempt | and attempt | |||
to reclaim or otherwise re-obtain its locks. It might find | to reclaim or otherwise re-obtain its locks. It might find | |||
that | that | |||
its file handle is now stale. However, if NFS4ERR_STALE is not | its filehandle is now stale. However, if NFS4ERR_STALE is not | |||
returned, it can proceed to reclaim or otherwise re-obtain its | returned, it can proceed to reclaim or otherwise re-obtain its | |||
open locking state. | open locking state. | |||
</t> | </li> | |||
<t> | <li> | |||
When eir_server_scope and | When eir_server_scope and | |||
eir_server_owner.so_major_id remain the same, | eir_server_owner.so_major_id remain the same, | |||
the client has to use the now-current values | the client has to use the now-current values | |||
of eir_server_owner.so_minor_id in deciding on appropriate | of eir_server_owner.so_minor_id in deciding on appropriate | |||
forms of trunking. This may result in connections being | forms of trunking. This may result in connections being | |||
dropped or new sessions being created. | dropped or new sessions being created. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <section anchor="PREP-trunk-verify" numbered="true" toc="default"> | |||
<section title="Verifying Claims of Matching Server Identity" | <name>Verifying Claims of Matching Server Identity</name> | |||
anchor="PREP-trunk-verify"> | <t> | |||
<t> | When the server responds using two different connections that claim | |||
When the server responds using two different connections claiming | ||||
matching or partially matching eir_server_owner, | matching or partially matching eir_server_owner, | |||
eir_server_scope, and eir_clientid values, the client | eir_server_scope, and eir_clientid values, the client | |||
does not have to trust the servers' claims. The client | does not have to trust the servers' claims. The client | |||
may verify these claims before trunking traffic in | may verify these claims before trunking traffic in | |||
the following ways: | the following ways: | |||
<list style='symbols'> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <li> | |||
<t> | ||||
For session trunking, | For session trunking, | |||
clients SHOULD | clients <bcp14>SHOULD</bcp14> | |||
reliably verify if connections between different | reliably verify if connections between different | |||
network paths are in fact associated with the same NFSv4.1 | network paths are in fact associated with the same NFSv4.1 | |||
server and usable on the same session, and servers | server and usable on the same session, and servers | |||
MUST allow clients to perform reliable verification. | <bcp14>MUST</bcp14> allow clients to perform reliable verification. | |||
When a client ID is created, the client SHOULD specify that | When a client ID is created, the client <bcp14>SHOULD</bcp14> specify that | |||
BIND_CONN_TO_SESSION is to be verified according to the | BIND_CONN_TO_SESSION is to be verified according to the | |||
SP4_SSV or SP4_MACH_CRED (<xref target="OP_EXCHANGE_ID" />) | SP4_SSV or SP4_MACH_CRED (<xref target="OP_EXCHANGE_ID" format="default"/> ) | |||
state protection options. For SP4_SSV, reliable | state protection options. For SP4_SSV, reliable | |||
verification depends on a shared secret (the | verification depends on a shared secret (the | |||
SSV) that is established via the SET_SSV (see | SSV) that is established via the SET_SSV (see | |||
<xref target="OP_SET_SSV" />) operation. | <xref target="OP_SET_SSV" format="default"/>) operation. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
When a new connection is associated with the | When a new connection is associated with the | |||
session (via the BIND_CONN_TO_SESSION operation, | session (via the BIND_CONN_TO_SESSION operation, | |||
see <xref target="OP_BIND_CONN_TO_SESSION" />), if | see <xref target="OP_BIND_CONN_TO_SESSION" format="default"/>), if | |||
the client specified SP4_SSV state protection for the | the client specified SP4_SSV state protection for the | |||
BIND_CONN_TO_SESSION operation, the client MUST send | BIND_CONN_TO_SESSION operation, the client <bcp14>MUST</bcp14> send | |||
the BIND_CONN_TO_SESSION with RPCSEC_GSS protection, | the BIND_CONN_TO_SESSION with RPCSEC_GSS protection, | |||
using integrity or privacy, and an RPCSEC_GSS handle created | using integrity or privacy, and an RPCSEC_GSS handle created | |||
with the GSS SSV mechanism (see <xref | with the GSS SSV mechanism (see <xref target="ssv_mech" format="default"/> | |||
target="ssv_mech" />). | ). | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
If the client mistakenly tries to associate a | If the client mistakenly tries to associate a | |||
connection to a session of a wrong server, the | connection to a session of a wrong server, the | |||
server will either reject the attempt because | server will either reject the attempt because | |||
it is not aware of the session identifier of the | it is not aware of the session identifier of the | |||
BIND_CONN_TO_SESSION arguments, or it will reject | BIND_CONN_TO_SESSION arguments, or it will reject | |||
the attempt because the RPCSEC_GSS authentication | the attempt because the RPCSEC_GSS authentication | |||
fails. Even if the server mistakenly or maliciously | fails. Even if the server mistakenly or maliciously | |||
accepts the connection association attempt, the | accepts the connection association attempt, the | |||
RPCSEC_GSS verifier it computes in the response | RPCSEC_GSS verifier it computes in the response | |||
will not be verified by the client, so the client will | will not be verified by the client, so the client will | |||
know it cannot use the connection for trunking the | know it cannot use the connection for trunking the | |||
specified session. <vspace blankLines='1' /> If the | specified session. </t> | |||
<t> If the | ||||
client specified SP4_MACH_CRED state protection, the | client specified SP4_MACH_CRED state protection, the | |||
BIND_CONN_TO_SESSION operation will use RPCSEC_GSS | BIND_CONN_TO_SESSION operation will use RPCSEC_GSS | |||
integrity or privacy, using the same credential that | integrity or privacy, using the same credential that | |||
was used when the client ID was created. Mutual | was used when the client ID was created. Mutual | |||
authentication via RPCSEC_GSS assures the client | authentication via RPCSEC_GSS assures the client | |||
that the connection is associated with the correct | that the connection is associated with the correct | |||
session of the correct server. | session of the correct server. | |||
<vspace blankLines='1' /> | </t> | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
For client ID trunking, the client has at least two | For client ID trunking, the client has at least two | |||
options for verifying that the same client ID | options for verifying that the same client ID | |||
obtained from two different EXCHANGE_ID operations | obtained from two different EXCHANGE_ID operations | |||
came from the same server. The first option is | came from the same server. The first option is | |||
to use RPCSEC_GSS authentication when sending each | to use RPCSEC_GSS authentication when sending each | |||
EXCHANGE_ID operation. Each time an EXCHANGE_ID is sent with | EXCHANGE_ID operation. Each time an EXCHANGE_ID is sent with | |||
RPCSEC_GSS authentication, the client notes the | RPCSEC_GSS authentication, the client notes the | |||
principal name of the GSS target. If the EXCHANGE_ID | principal name of the GSS target. If the EXCHANGE_ID | |||
results indicate that client ID trunking is possible, | results indicate that client ID trunking is possible, | |||
and the GSS targets' principal names are the same, | and the GSS targets' principal names are the same, | |||
the servers are the same and client ID trunking is | the servers are the same and client ID trunking is | |||
allowed. | allowed. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
The second option for verification is to | The second option for verification is to | |||
use SP4_SSV protection. When the client sends | use SP4_SSV protection. When the client sends | |||
EXCHANGE_ID, it specifies SP4_SSV protection. The | EXCHANGE_ID, it specifies SP4_SSV protection. The | |||
first EXCHANGE_ID the client sends always has to | first EXCHANGE_ID the client sends always has to | |||
be confirmed by a CREATE_SESSION call. The client | be confirmed by a CREATE_SESSION call. The client | |||
then sends SET_SSV. Later, the client | then sends SET_SSV. Later, the client | |||
sends EXCHANGE_ID to a second destination | sends EXCHANGE_ID to a second destination | |||
network address different from the one the first | network address different from the one the first | |||
EXCHANGE_ID was sent to. | EXCHANGE_ID was sent to. | |||
skipping to change at line 3039 ¶ | skipping to change at line 3020 ¶ | |||
claim by sending a CREATE_SESSION operation to the second | claim by sending a CREATE_SESSION operation to the second | |||
destination address, protected with RPCSEC_GSS integrity | destination address, protected with RPCSEC_GSS integrity | |||
using an RPCSEC_GSS handle returned by the second | using an RPCSEC_GSS handle returned by the second | |||
EXCHANGE_ID. If the server accepts the CREATE_SESSION | EXCHANGE_ID. If the server accepts the CREATE_SESSION | |||
request, and if the client verifies the RPCSEC_GSS | request, and if the client verifies the RPCSEC_GSS | |||
verifier and integrity codes, then the client has | verifier and integrity codes, then the client has | |||
proof the second server knows the SSV, and thus | proof the second server knows the SSV, and thus | |||
the two servers are cooperating for the purposes of | the two servers are cooperating for the purposes of | |||
specifying server scope and client ID trunking. | specifying server scope and client ID trunking. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ul> | |||
</section> | ||||
</section> | </section> | |||
</section> | <section anchor="Exactly_Once_Semantics" numbered="true" toc="default"> | |||
<name>Exactly Once Semantics</name> | ||||
<section anchor="Exactly_Once_Semantics" title="Exactly Once Semantics"> | <t> | |||
<t> | ||||
Via the session, NFSv4.1 offers exactly once semantics (EOS) | Via the session, NFSv4.1 offers exactly once semantics (EOS) | |||
for requests sent over a channel. EOS is supported on both the | for requests sent over a channel. EOS is supported on both the | |||
fore channel and backchannel. | fore channel and backchannel. | |||
</t> | </t> | |||
<t> | <t> | |||
Each COMPOUND or CB_COMPOUND request that is sent | Each COMPOUND or CB_COMPOUND request that is sent | |||
with a leading SEQUENCE or CB_SEQUENCE operation MUST | with a leading SEQUENCE or CB_SEQUENCE operation <bcp14>MUST</bcp14> | |||
be executed by the receiver exactly once. This requirement | be executed by the receiver exactly once. This requirement | |||
holds regardless of whether the request is sent with reply | holds regardless of whether the request is sent with reply | |||
caching specified (see <xref target="optional_reply_caching" />). | caching specified (see <xref target="optional_reply_caching" format="default" />). | |||
The requirement holds even if the requester is sending the | The requirement holds even if the requester is sending the | |||
request over a session created between a pNFS data client | request over a session created between a pNFS data client | |||
and pNFS data server. To understand the rationale for this requirement, | and pNFS data server. To understand the rationale for this requirement, | |||
divide the requests into three | divide the requests into three | |||
classifications: | classifications: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Non-idempotent requests. | Non-idempotent requests. | |||
</t> | </li> | |||
<t> | <li> | |||
Idempotent modifying requests. | Idempotent modifying requests. | |||
</t> | </li> | |||
<t> | <li> | |||
Idempotent non-modifying requests. | Idempotent non-modifying requests. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
An example of a non-idempotent request is | An example of a non-idempotent request is | |||
RENAME. Obviously, if a replier executes the | RENAME. Obviously, if a replier executes the | |||
same RENAME request twice, and the first execution succeeds, | same RENAME request twice, and the first execution succeeds, | |||
the re-execution will fail. If the replier returns the | the re-execution will fail. If the replier returns the | |||
result from the re-execution, this result is incorrect. | result from the re-execution, this result is incorrect. | |||
Therefore, EOS is required for non-idempotent requests. | Therefore, EOS is required for non-idempotent requests. | |||
</t> | </t> | |||
<t> | <t> | |||
An example of an idempotent modifying request is | An example of an idempotent modifying request is | |||
a COMPOUND request containing a WRITE operation. | a COMPOUND request containing a WRITE operation. | |||
Repeated execution of the same WRITE | Repeated execution of the same WRITE | |||
has the same effect as execution of that WRITE a single time. | has the same effect as execution of that WRITE a single time. | |||
Nevertheless, enforcing EOS for WRITEs and other idempotent | Nevertheless, enforcing EOS for WRITEs and other idempotent | |||
modifying requests is necessary | modifying requests is necessary | |||
to avoid data corruption. | to avoid data corruption. | |||
</t> | </t> | |||
<t> | <t> | |||
Suppose a client sends WRITE A to a | Suppose a client sends WRITE A to a | |||
noncompliant server that does not enforce EOS, and | noncompliant server that does not enforce EOS, and | |||
receives no response, perhaps due to a network | receives no response, perhaps due to a network | |||
partition. The client reconnects to the server and | partition. The client reconnects to the server and | |||
re-sends WRITE A. Now, the server has | re-sends WRITE A. Now, the server has | |||
outstanding two instances of A. The | outstanding two instances of A. The | |||
server can be in a situation in which it executes and | server can be in a situation in which it executes and | |||
replies to the retry of A, while the first | replies to the retry of A, while the first | |||
A is still waiting in the server's internal I/O system for some | A is still waiting in the server's internal I/O system for some | |||
resource. Upon receiving the | resource. Upon receiving the | |||
reply to the second attempt of WRITE A, | reply to the second attempt of WRITE A, | |||
the client believes its WRITE is done so it is free | the client believes its WRITE is done so it is free | |||
to send WRITE B, which overlaps the byte-range of | to send WRITE B, which overlaps the byte-range of | |||
A. When the original A is dispatched from the server's | A. When the original A is dispatched from the server's | |||
I/O system and | I/O system and | |||
executed (thus the second time A will have | executed (thus the second time A will have | |||
been written), then what has been | been written), then what has been | |||
written by B can be overwritten and thus corrupted. | written by B can be overwritten and thus corrupted. | |||
</t> | </t> | |||
<t> | <t> | |||
An example of an idempotent non-modifying request | An example of an idempotent non-modifying request | |||
is a COMPOUND containing SEQUENCE, PUTFH, READLINK, | is a COMPOUND containing SEQUENCE, PUTFH, READLINK, | |||
and nothing else. The re-execution of such a | and nothing else. The re-execution of such a | |||
request will not cause data corruption or | request will not cause data corruption or | |||
produce an incorrect result. Nonetheless, | produce an incorrect result. Nonetheless, | |||
to keep the implementation simple, | to keep the implementation simple, | |||
the replier MUST enforce EOS for all requests, whether or not | the replier <bcp14>MUST</bcp14> enforce EOS for all requests, whether or not | |||
idempotent and non-modifying. | idempotent and non-modifying. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that true and complete EOS is not possible unless the | Note that true and complete EOS is not possible unless the | |||
server persists the reply cache in stable storage, and unless the | server persists the reply cache in stable storage, and unless the | |||
server is somehow implemented to never require a restart | server is somehow implemented to never require a restart | |||
(indeed, if such a server exists, the distinction between a | (indeed, if such a server exists, the distinction between a | |||
reply cache kept in stable storage versus one that is not is | reply cache kept in stable storage versus one that is not is | |||
one without meaning). See <xref target="Persistence" /> for | one without meaning). See <xref target="Persistence" format="default"/> for | |||
a discussion of persistence in the reply cache. | a discussion of persistence in the reply cache. | |||
Regardless, even if the server does not persist the reply cache, | Regardless, even if the server does not persist the reply cache, | |||
EOS improves robustness and correctness over previous versions | EOS improves robustness and correctness over previous versions | |||
of NFS because the legacy duplicate request/reply caches were | of NFS because the legacy duplicate request/reply caches were | |||
based on the ONC RPC transaction identifier (XID). | based on the ONC RPC transaction identifier (XID). | |||
<xref target="Slot_Identifiers_and_Server_Reply_Cache" /> | <xref target="Slot_Identifiers_and_Server_Reply_Cache" format="default"/> | |||
explains the shortcomings of the XID as a basis for | explains the shortcomings of the XID as a basis for | |||
a reply cache and describes how NFSv4.1 sessions improve | a reply cache and describes how NFSv4.1 sessions improve | |||
upon the XID. | upon the XID. | |||
</t> | </t> | |||
<section anchor="Slot_Identifiers_and_Server_Reply_Cache" numbered="tr | ||||
<section anchor="Slot_Identifiers_and_Server_Reply_Cache" | ue" toc="default"> | |||
title="Slot Identifiers and Reply Cache"> | <name>Slot Identifiers and Reply Cache</name> | |||
<t> | <t> | |||
The RPC layer provides a transaction ID (XID), which, | The RPC layer provides a transaction ID (XID), which, | |||
while required to be unique, is not | while required to be unique, is not | |||
convenient for tracking requests for two reasons. | convenient for tracking requests for two reasons. | |||
First, the XID is only | First, the XID is only | |||
meaningful to the requester; it cannot be interpreted | meaningful to the requester; it cannot be interpreted | |||
by the replier except to test for equality with | by the replier except to test for equality with | |||
previously sent requests. When consulting an RPC-based | previously sent requests. When consulting an RPC-based | |||
duplicate request cache, the opaqueness of the XID requires | duplicate request cache, the opaqueness of the XID requires | |||
a computationally expensive look up (often via a hash that | a computationally expensive look up (often via a hash that | |||
includes XID and source address). NFSv4.1 requests use | includes XID and source address). NFSv4.1 requests use | |||
a non-opaque slot ID, which is an index into a slot table, | a non-opaque slot ID, which is an index into a slot table, | |||
which is far more efficient. Second, because RPC requests | which is far more efficient. Second, because RPC requests | |||
can be executed by the replier in any order, there is | can be executed by the replier in any order, there is | |||
no bound on the number of requests that may be outstanding | no bound on the number of requests that may be outstanding | |||
at any time. To achieve perfect EOS, using ONC RPC | at any time. To achieve perfect EOS, using ONC RPC | |||
would require storing all replies in the reply cache. | would require storing all replies in the reply cache. | |||
XIDs are 32 bits; storing over four billion (2^32) replies | XIDs are 32 bits; storing over four billion (2<sup>32</sup>) replies | |||
in the reply cache is not practical. In practice, previous versions | in the reply cache is not practical. In practice, previous versions | |||
of NFS have chosen to store a fixed number of replies in | of NFS have chosen to store a fixed number of replies in | |||
the cache, and to use a least recently used (LRU) approach to | the cache, and to use a least recently used (LRU) approach to | |||
replacing cache entries with new entries when the cache | replacing cache entries with new entries when the cache | |||
is full. In NFSv4.1, the number of outstanding requests is | is full. In NFSv4.1, the number of outstanding requests is | |||
bounded by the size of the slot table, and a sequence ID | bounded by the size of the slot table, and a sequence ID | |||
per slot is used to tell the replier when it is safe to | per slot is used to tell the replier when it is safe to | |||
delete a cached reply. | delete a cached reply. | |||
</t> | </t> | |||
<t> | <t> | |||
In the NFSv4.1 reply cache, when the requester sends a new request, | In the NFSv4.1 reply cache, when the requester sends a new request, | |||
it selects a slot ID in the | it selects a slot ID in the | |||
range 0..N, where N is the replier's current maximum slot ID | range 0..N, where N is the replier's current maximum slot ID | |||
granted to the requester on the session over which the request is to be | granted to the requester on the session over which the request is to be | |||
sent. The value of N starts out as equal to | sent. The value of N starts out as equal to | |||
ca_maxrequests - 1 (<xref target="OP_CREATE_SESSION" />), but | ca_maxrequests - 1 (<xref target="OP_CREATE_SESSION" format="default"/>), b ut | |||
can be adjusted by the response to SEQUENCE or CB_SEQUENCE as described | can be adjusted by the response to SEQUENCE or CB_SEQUENCE as described | |||
later in this section. | later in this section. | |||
The slot ID must be unused by any of the requests that the | The slot ID must be unused by any of the requests that the | |||
requester has already active on the session. "Unused" here means the | requester has already active on the session. "Unused" here means the | |||
requester has no outstanding request for that slot ID. | requester has no outstanding request for that slot ID. | |||
</t> | </t> | |||
<t> | <t> | |||
A slot contains a sequence ID and the cached reply corresponding to | A slot contains a sequence ID and the cached reply corresponding to | |||
the request sent with that sequence ID. The sequence ID is a | the request sent with that sequence ID. The sequence ID is a | |||
32-bit unsigned value, and is therefore in the range 0..0xFFFFFFFF (2^32 - | 32-bit unsigned value, and is therefore in the range 0..0xFFFFFFFF (2<sup>3 | |||
1). | 2</sup> - 1). | |||
The first time a slot is used, the requester MUST specify | The first time a slot is used, the requester <bcp14>MUST</bcp14> specify | |||
a sequence ID of one (<xref target="OP_CREATE_SESSION" />). | a sequence ID of one (<xref target="OP_CREATE_SESSION" format="default"/>). | |||
Each time a slot is reused, the request MUST specify a sequence ID | Each time a slot is reused, the request <bcp14>MUST</bcp14> specify a seque | |||
nce ID | ||||
that is one greater than that of the previous request on the | that is one greater than that of the previous request on the | |||
slot. If the previous sequence ID was 0xFFFFFFFF, then the next | slot. If the previous sequence ID was 0xFFFFFFFF, then the next | |||
request for the slot MUST have the sequence ID set to zero (i.e., | request for the slot <bcp14>MUST</bcp14> have the sequence ID set to zero ( | |||
(2^32 - 1) + 1 mod 2^32). | i.e., | |||
</t> | (2<sup>32</sup> - 1) + 1 mod 2<sup>32</sup>). | |||
<t> | </t> | |||
<t> | ||||
The sequence ID accompanies the slot ID in each request. It is | The sequence ID accompanies the slot ID in each request. It is | |||
for the critical check at the replier: it used to efficiently | for the critical check at the replier: it used to efficiently | |||
determine whether a request using a certain | determine whether a request using a certain | |||
slot ID is a retransmit or a new, never-before-seen request. It is | slot ID is a retransmit or a new, never-before-seen request. It is | |||
not feasible for the requester to assert that it is retransmitting to | not feasible for the requester to assert that it is retransmitting to | |||
implement this, because for any given request the requester cannot | implement this, because for any given request the requester cannot | |||
know whether the replier has seen it unless the replier actually replies. Of | know whether the replier has seen it unless the replier actually replies. Of | |||
course, if the requester has seen the reply, the requester would | course, if the requester has seen the reply, the requester would | |||
not retransmit. | not retransmit. | |||
</t> | </t> | |||
<t> | <t> | |||
The replier compares each received request's | The replier compares each received request's | |||
sequence ID with the last one previously received for that slot ID, | sequence ID with the last one previously received for that slot ID, | |||
to see if the new request is: | to see if the new request is: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style="symbols"> | <li> | |||
<t> | ||||
A new request, in which the sequence ID is one greater | A new request, in which the sequence ID is one greater | |||
than that previously seen in the slot (accounting for sequence | than that previously seen in the slot (accounting for sequence | |||
wraparound). The replier proceeds to execute the new request, | wraparound). The replier proceeds to execute the new request, | |||
and the replier | and the replier | |||
MUST increase the slot's sequence ID by one. | <bcp14>MUST</bcp14> increase the slot's sequence ID by one. | |||
</t> | </li> | |||
<t> | <li> | |||
A retransmitted request, in which the sequence ID is equal to | A retransmitted request, in which the sequence ID is equal to | |||
that currently recorded in the slot. | that currently recorded in the slot. | |||
If the original request has | If the original request has | |||
executed to completion, the replier returns the cached | executed to completion, the replier returns the cached | |||
reply. See <xref target="Retry_and_Replay" /> for direction on how the rep lier | reply. See <xref target="Retry_and_Replay" format="default"/> for directio n on how the replier | |||
deals with retries of requests that are still in progress. | deals with retries of requests that are still in progress. | |||
</t> | </li> | |||
<t> | <li> | |||
A misordered retry, in which the sequence ID | A misordered retry, in which the sequence ID | |||
is less than (accounting for sequence wraparound) | is less than (accounting for sequence wraparound) | |||
that previously seen in the slot. The | that previously seen in the slot. The | |||
replier MUST return NFS4ERR_SEQ_MISORDERED (as the | replier <bcp14>MUST</bcp14> return NFS4ERR_SEQ_MISORDERED (as the | |||
result from SEQUENCE or CB_SEQUENCE). | result from SEQUENCE or CB_SEQUENCE). | |||
</t> | </li> | |||
<t> | <li> | |||
A misordered new request, in which the sequence ID | A misordered new request, in which the sequence ID | |||
is two or more than (accounting for sequence | is two or more than (accounting for sequence | |||
wraparound) that previously seen in the | wraparound) that previously seen in the | |||
slot. Note that because the sequence ID MUST | slot. Note that because the sequence ID <bcp14>MUST</bcp14> | |||
wrap around to zero once it reaches 0xFFFFFFFF, a | wrap around to zero once it reaches 0xFFFFFFFF, a | |||
misordered new request and a misordered retry | misordered new request and a misordered retry | |||
cannot be distinguished. Thus, the replier MUST | cannot be distinguished. Thus, the replier <bcp14>MUST</bcp14> | |||
return NFS4ERR_SEQ_MISORDERED (as the result from | return NFS4ERR_SEQ_MISORDERED (as the result from | |||
SEQUENCE or CB_SEQUENCE). | SEQUENCE or CB_SEQUENCE). | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Unlike the XID, the slot ID is always within a specific | Unlike the XID, the slot ID is always within a specific | |||
range; this has two implications. The first | range; this has two implications. The first | |||
implication is that for a given session, the replier | implication is that for a given session, the replier | |||
need only cache the results of a limited number of | need only cache the results of a limited number of | |||
COMPOUND requests. | COMPOUND requests. | |||
The second implication derives | The second implication derives | |||
from the first, which is that unlike XID-indexed reply | from the first, which is that unlike XID-indexed reply | |||
caches (also known as duplicate request caches - DRCs), | caches (also known as duplicate request caches - DRCs), | |||
the slot ID-based reply cache cannot be overflowed. | the slot ID-based reply cache cannot be overflowed. | |||
Through use of the sequence ID to identify | Through use of the sequence ID to identify | |||
retransmitted requests, the replier does not need to | retransmitted requests, the replier does not need to | |||
actually cache the request itself, reducing the | actually cache the request itself, reducing the | |||
storage requirements of the reply cache further. These | storage requirements of the reply cache further. These | |||
facilities make it practical to maintain all the | facilities make it practical to maintain all the | |||
required entries for an effective reply cache. | required entries for an effective reply cache. | |||
</t> | </t> | |||
<t> | <t> | |||
The slot ID, sequence ID, and session ID therefore take over the traditiona l role | The slot ID, sequence ID, and session ID therefore take over the traditiona l role | |||
of the XID and source network address in the replier's | of the XID and source network address in the replier's | |||
reply cache implementation. | reply cache implementation. | |||
This approach is considerably | This approach is considerably | |||
more portable and completely robust -- it is not subject to the | more portable and completely robust -- it is not subject to the | |||
reassignment of ports as clients reconnect over IP | reassignment of ports as clients reconnect over IP | |||
networks. In addition, the RPC XID is not used in the reply cache, | networks. In addition, the RPC XID is not used in the reply cache, | |||
enhancing robustness of the cache in the face of any rapid reuse of | enhancing robustness of the cache in the face of any rapid reuse of | |||
XIDs by the requester. While the replier does not care | XIDs by the requester. While the replier does not care | |||
about the XID for the purposes of reply cache management | about the XID for the purposes of reply cache management | |||
(but the replier MUST return the same XID that was in the request), | (but the replier <bcp14>MUST</bcp14> return the same XID that was in the re quest), | |||
nonetheless there are considerations for the XID in NFSv4.1 | nonetheless there are considerations for the XID in NFSv4.1 | |||
that are the same as all other previous versions of NFS. | that are the same as all other previous versions of NFS. | |||
The RPC XID remains in each message and needs to be formulated | The RPC XID remains in each message and needs to be formulated | |||
in NFSv4.1 requests as in any other ONC RPC request. The reasons | in NFSv4.1 requests as in any other ONC RPC request. The reasons | |||
include: | include: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The RPC layer retains its existing semantics and implementation. | The RPC layer retains its existing semantics and implementation. | |||
</t> | </li> | |||
<t> | <li> | |||
The requester and replier must be able to interoperate at the | The requester and replier must be able to interoperate at the | |||
RPC layer, prior to the NFSv4.1 decoding of the SEQUENCE or CB_SEQUENCE | RPC layer, prior to the NFSv4.1 decoding of the SEQUENCE or CB_SEQUENCE | |||
operation. | operation. | |||
</t> | </li> | |||
<t> | <li> | |||
If an operation is being used that does not start with | If an operation is being used that does not start with | |||
SEQUENCE or CB_SEQUENCE (e.g., BIND_CONN_TO_SESSION), | SEQUENCE or CB_SEQUENCE (e.g., BIND_CONN_TO_SESSION), | |||
then the RPC XID is needed for correct operation to | then the RPC XID is needed for correct operation to | |||
match the reply to the request. | match the reply to the request. | |||
</t> | </li> | |||
<t> | <li> | |||
The SEQUENCE or CB_SEQUENCE operation may generate an error. | The SEQUENCE or CB_SEQUENCE operation may generate an error. | |||
If so, the embedded slot ID, sequence ID, and session ID (if | If so, the embedded slot ID, sequence ID, and session ID (if | |||
present) in the request will not be in the reply, and the | present) in the request will not be in the reply, and the | |||
requester has only the XID to match the reply to the request. | requester has only the XID to match the reply to the request. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Given that well-formulated XIDs continue to be required, | Given that well-formulated XIDs continue to be required, | |||
this raises the question: why do SEQUENCE and CB_SEQUENCE replies | this raises the question: why do SEQUENCE and CB_SEQUENCE replies | |||
have a session ID, slot ID, and sequence ID? Having the session ID | have a session ID, slot ID, and sequence ID? Having the session ID | |||
in the reply means that the requester does not have to use the | in the reply means that the requester does not have to use the | |||
XID to look up | XID to look up | |||
the session ID, which would be necessary if the connection were | the session ID, which would be necessary if the connection were | |||
associated with multiple sessions. Having the slot ID and sequence ID | associated with multiple sessions. Having the slot ID and sequence ID | |||
in the reply means that the requester does not have to use the XID to | in the reply means that the requester does not have to use the XID to | |||
look up the slot ID and sequence ID. | look up the slot ID and sequence ID. | |||
Furthermore, since the XID is only 32 bits, it is too small to | Furthermore, since the XID is only 32 bits, it is too small to | |||
guarantee the re-association of a reply with its request | guarantee the re-association of a reply with its request | |||
<xref target="rpc_xid_issues" />; having | <xref target="rpc_xid_issues" format="default"/>; having | |||
session ID, slot ID, and sequence ID in the reply allows the | session ID, slot ID, and sequence ID in the reply allows the | |||
client to validate that the reply in fact belongs to the matched request. | client to validate that the reply in fact belongs to the matched request. | |||
</t> | </t> | |||
<t> | <t> | |||
The SEQUENCE (and CB_SEQUENCE) operation also carries | The SEQUENCE (and CB_SEQUENCE) operation also carries | |||
a "highest_slotid" value, which carries additional | a "highest_slotid" value, which carries additional | |||
requester slot usage information. The requester MUST | requester slot usage information. The requester <bcp14>MUST</bcp14> | |||
always indicate the slot ID representing the outstanding request with the | always indicate the slot ID representing the outstanding request with the | |||
highest-numbered slot | highest-numbered slot | |||
value. | value. | |||
The requester should in all cases provide the most | The requester should in all cases provide the most | |||
conservative value possible, although it can be increased somewhat | conservative value possible, although it can be increased somewhat | |||
above the actual instantaneous usage to maintain some minimum or | above the actual instantaneous usage to maintain some minimum or | |||
optimal level. This provides a way for the requester to yield unused | optimal level. This provides a way for the requester to yield unused | |||
request slots back to the replier, which in turn can use the | request slots back to the replier, which in turn can use the | |||
information to reallocate resources. | information to reallocate resources. | |||
</t> | </t> | |||
<t> | <t> | |||
The replier | The replier | |||
responds with both a new target highest_slotid and an | responds with both a new target highest_slotid and an | |||
enforced highest_slotid, described as follows: | enforced highest_slotid, described as follows: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
The target highest_slotid is | The target highest_slotid is | |||
an indication to the requester of the highest_slotid the replier | an indication to the requester of the highest_slotid the replier | |||
wishes the requester to be using. This permits the replier to withdraw | wishes the requester to be using. This permits the replier to withdraw | |||
(or add) resources from a requester that has been found to not be | (or add) resources from a requester that has been found to not be | |||
using them, in order to more fairly share resources among a varying | using them, in order to more fairly share resources among a varying | |||
level of demand from other requesters. The requester must always comply | level of demand from other requesters. The requester must always comply | |||
with the replier's value updates, since they indicate newly | with the replier's value updates, since they indicate newly | |||
established hard limits on the requester's access to session | established hard limits on the requester's access to session | |||
resources. However, because of request pipelining, the requester may | resources. However, because of request pipelining, the requester may | |||
have active requests in flight reflecting prior values; therefore, | have active requests in flight reflecting prior values; therefore, | |||
the replier must not immediately require the requester to comply. | the replier must not immediately require the requester to comply. | |||
<vspace blankLines='1' /> | </t> | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
The enforced highest_slotid indicates the highest slot ID | The enforced highest_slotid indicates the highest slot ID | |||
the requester is permitted to use on a subsequent SEQUENCE or | the requester is permitted to use on a subsequent SEQUENCE or | |||
CB_SEQUENCE operation. The replier's enforced highest_slotid SHOULD | CB_SEQUENCE operation. The replier's enforced highest_slotid <bcp14>SHOULD </bcp14> | |||
be no less than the highest_slotid the requester indicated | be no less than the highest_slotid the requester indicated | |||
in the SEQUENCE or CB_SEQUENCE arguments. | in the SEQUENCE or CB_SEQUENCE arguments. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
A requester can be intransigent with respect to lowering its | A requester can be intransigent with respect to lowering its | |||
highest_slotid argument to a Sequence operation, i.e. the requester | highest_slotid argument to a Sequence operation, i.e. the requester | |||
continues to ignore the target highest_slotid in the response to | continues to ignore the target highest_slotid in the response to | |||
a Sequence operation, and continues to set its highest_slotid | a Sequence operation, and continues to set its highest_slotid | |||
argument to be higher than the target highest_slotid. This can | argument to be higher than the target highest_slotid. This can | |||
be considered particularly egregious behavior when the replier | be considered particularly egregious behavior when the replier | |||
knows there are no outstanding requests with slot IDs higher than | knows there are no outstanding requests with slot IDs higher than | |||
its target highest_slotid. When faced with such intransigence, | its target highest_slotid. When faced with such intransigence, | |||
the replier is free to take more forceful action, and MAY reply with | the replier is free to take more forceful action, and <bcp14>MAY</bcp14> r eply with | |||
a new enforced highest_slotid that is less than its previous | a new enforced highest_slotid that is less than its previous | |||
enforced highest_slotid. Thereafter, if the requester continues | enforced highest_slotid. Thereafter, if the requester continues | |||
to send requests with a highest_slotid that is greater than | to send requests with a highest_slotid that is greater than | |||
the replier's new enforced highest_slotid, the server MAY return | the replier's new enforced highest_slotid, the server <bcp14>MAY</bcp14> r eturn | |||
NFS4ERR_BAD_HIGH_SLOT, unless the slot ID in the request is greater | NFS4ERR_BAD_HIGH_SLOT, unless the slot ID in the request is greater | |||
than the new enforced highest_slotid and the request is a retry. | than the new enforced highest_slotid and the request is a retry. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
The replier SHOULD retain the slots it wants to retire | The replier <bcp14>SHOULD</bcp14> retain the slots it wants to retire | |||
until | until | |||
the requester sends a request with a highest_slotid less than | the requester sends a request with a highest_slotid less than | |||
or equal to the replier's new enforced highest_slotid. | or equal to the replier's new enforced highest_slotid. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
The requester can also be intransigent with | The requester can also be intransigent with | |||
respect to sending non-retry requests that have a slot ID that | respect to sending non-retry requests that have a slot ID that | |||
exceeds the replier's highest_slotid. | exceeds the replier's highest_slotid. | |||
Once the replier has forcibly lowered the enforced | Once the replier has forcibly lowered the enforced | |||
highest_slotid, the requester is only allowed to | highest_slotid, the requester is only allowed to | |||
send retries on slots that exceed the replier's highest_slotid. | send retries on slots that exceed the replier's highest_slotid. | |||
If a request is received with a slot ID that is higher than | If a request is received with a slot ID that is higher than | |||
the new enforced highest_slotid, and the sequence ID | the new enforced highest_slotid, and the sequence ID | |||
is one higher than what is in the slot's reply cache, then | is one higher than what is in the slot's reply cache, then | |||
the server can both retire the slot and return NFS4ERR_BADSLOT | the server can both retire the slot and return NFS4ERR_BADSLOT | |||
(however, the server MUST NOT do one and not the other). | (however, the server <bcp14>MUST NOT</bcp14> do one and not the other). | |||
The reason it is safe to retire the slot | The reason it is safe to retire the slot | |||
is because by using the next sequence ID, the requester | is because by using the next sequence ID, the requester | |||
is indicating it has received the previous reply for the | is indicating it has received the previous reply for the | |||
slot. | slot. | |||
<vspace blankLines='1' /> | </t> | |||
</t> | </li> | |||
<t> | <li> | |||
The requester SHOULD use the lowest available | The requester <bcp14>SHOULD</bcp14> use the lowest available | |||
slot when sending a new request. This way, the | slot when sending a new request. This way, the | |||
replier may be able to retire slot entries faster. | replier may be able to retire slot entries faster. | |||
However, where the replier is actively adjusting | However, where the replier is actively adjusting | |||
its granted highest_slotid, | its granted highest_slotid, | |||
it will not be able | it will not be able | |||
to use only the receipt of the slot ID and highest_slotid | to use only the receipt of the slot ID and highest_slotid | |||
in the request. Neither the slot ID nor the | in the request. Neither the slot ID nor the | |||
highest_slotid used in a request may reflect the | highest_slotid used in a request may reflect the | |||
replier's current idea of the requester's session | replier's current idea of the requester's session | |||
limit, because the request may have been sent from the | limit, because the request may have been sent from the | |||
requester before the update was received. Therefore, | requester before the update was received. Therefore, | |||
in the downward adjustment case, the replier may have | in the downward adjustment case, the replier may have | |||
to retain a number of reply cache entries at least as | to retain a number of reply cache entries at least as | |||
large as the old value of maximum requests | large as the old value of maximum requests | |||
outstanding, until it can infer that the requester | outstanding, until it can infer that the requester | |||
has seen a reply containing the new granted highest_slotid. | has seen a reply containing the new granted highest_slotid. | |||
The replier can infer that the requester has seen such a | The replier can infer that the requester has seen such a | |||
reply when it receives a new request with the same | reply when it receives a new request with the same | |||
slot ID as the request replied to and the next higher | slot ID as the request replied to and the next higher | |||
sequence ID. | sequence ID. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <section anchor="cacheseq" numbered="true" toc="default"> | |||
<section title="Caching of SEQUENCE and CB_SEQUENCE Replies" anchor="caches | <name>Caching of SEQUENCE and CB_SEQUENCE Replies</name> | |||
eq"> | <t> | |||
<t> | ||||
When a SEQUENCE or CB_SEQUENCE operation is | When a SEQUENCE or CB_SEQUENCE operation is | |||
successfully executed, its reply MUST always be | successfully executed, its reply <bcp14>MUST</bcp14> always be | |||
cached. Specifically, session ID, sequence ID, | cached. Specifically, session ID, sequence ID, | |||
and slot ID MUST be cached in the reply cache. | and slot ID <bcp14>MUST</bcp14> be cached in the reply cache. | |||
The reply from SEQUENCE also includes the highest | The reply from SEQUENCE also includes the highest | |||
slot ID, target highest slot ID, and status flags. Instead | slot ID, target highest slot ID, and status flags. Instead | |||
of caching these values, the server MAY | of caching these values, the server <bcp14>MAY</bcp14> | |||
re-compute the values from the current | re-compute the values from the current | |||
state of the fore channel, session, and/or client | state of the fore channel, session, and/or client | |||
ID as appropriate. Similarly, the reply from | ID as appropriate. Similarly, the reply from | |||
CB_SEQUENCE includes a highest slot ID and target | CB_SEQUENCE includes a highest slot ID and target | |||
highest slot ID. The client | highest slot ID. The client | |||
MAY re-compute the values from the | <bcp14>MAY</bcp14> re-compute the values from the | |||
current state of the session as appropriate. | current state of the session as appropriate. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
Regardless of whether or not a replier is re-computing highest slot ID, | Regardless of whether or not a replier is re-computing highest slot ID, | |||
target slot ID, and status on replies to retries, the requester | target slot ID, and status on replies to retries, the requester | |||
MUST NOT assume that the values are being re-computed whenever it | <bcp14>MUST NOT</bcp14> assume that the values are being re-computed when ever it | |||
receives a reply after a retry is sent, since it has no way | receives a reply after a retry is sent, since it has no way | |||
of knowing whether the reply it has received was sent by the | of knowing whether the reply it has received was sent by the | |||
replier in response to the retry or is a delayed response to | replier in response to the retry or is a delayed response to | |||
the original request. Therefore, it may be the case that | the original request. Therefore, it may be the case that | |||
highest slot ID, target slot ID, or status bits may reflect | highest slot ID, target slot ID, or status bits may reflect | |||
the state of affairs when the request was first executed. | the state of affairs when the request was first executed. | |||
Although acting based on such delayed information is valid, | Although acting based on such delayed information is valid, | |||
it may cause the receiver of the reply to do unneeded work. Requesters | it may cause the receiver of the reply to do unneeded work. Requesters | |||
MAY choose to send additional requests to get the current | <bcp14>MAY</bcp14> choose to send additional requests to get the current | |||
state of affairs or use the state of affairs reported by | state of affairs or use the state of affairs reported by | |||
subsequent requests, in preference to acting immediately | subsequent requests, in preference to acting immediately | |||
on data that might be out of date. | on data that might be out of date. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section anchor="err_sequence" numbered="true" toc="default"> | |||
<name>Errors from SEQUENCE and CB_SEQUENCE</name> | ||||
<section title="Errors from SEQUENCE and CB_SEQUENCE" | <t> | |||
anchor="err_sequence"> | ||||
<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 MUST NOT change. The replier MUST NOT | 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> <!-- Errors from SEQUENCE and CB_SEQUENCE --> | </section> | |||
<section title="Optional Reply Caching" | <section anchor="optional_reply_caching" numbered="true" toc="default"> | |||
anchor="optional_reply_caching"> | <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 | |||
idempotent operations <xref target="Chet" />. | idempotent operations <xref target="Chet" format="default"/>. | |||
Caching the reply may offer little benefit. If | Caching the reply may offer little benefit. If | |||
the reply is too large (see | the reply is too large (see | |||
<xref target="COMPOUND_Sizing_Issues" />), | <xref target="COMPOUND_Sizing_Issues" format="default"/>), | |||
it may not be cacheable anyway. Even if the reply to | it may not be cacheable anyway. Even if the reply to | |||
idempotent request is small enough to cache, unnecessarily | idempotent request is small enough to cache, unnecessarily | |||
caching the reply slows down the server and increases | caching the reply slows down the server and increases | |||
RPC latency. | RPC latency. | |||
</t> | </t> | |||
<t> | <t> | |||
Whether or not the requester requests the reply to be cached | Whether or not the requester requests the reply to be cached | |||
has no effect on the slot processing. If the | has no effect on the slot processing. If the | |||
result of SEQUENCE or CB_SEQUENCE is NFS4_OK, then | result of SEQUENCE or CB_SEQUENCE is NFS4_OK, then | |||
the slot's sequence ID MUST be incremented by one. | the slot's sequence ID <bcp14>MUST</bcp14> be incremented by one. | |||
If a requester does not direct the replier to cache | If a requester does not direct the replier to cache | |||
the reply, the replier MUST do one of following: | the reply, the replier <bcp14>MUST</bcp14> do one of following: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The replier can cache the entire original reply. | The replier can cache the entire original reply. | |||
Even though sa_cachethis or csa_cachethis is FALSE, | Even though sa_cachethis or csa_cachethis is FALSE, | |||
the replier is always free to cache. It may choose | the replier is always free to cache. It may choose | |||
this approach in order to simplify implementation. | this approach in order to simplify implementation. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
The replier enters into its reply cache a reply consisting | The replier enters into its reply cache a reply consisting | |||
of the original results to the SEQUENCE or CB_SEQUENCE | of the original results to the SEQUENCE or CB_SEQUENCE | |||
operation, and with the next operation in | operation, and with the next operation in | |||
COMPOUND or CB_COMPOUND having the error NFS4ERR_RETRY_UNCACHED_REP. | COMPOUND or CB_COMPOUND having the error NFS4ERR_RETRY_UNCACHED_REP. | |||
Thus, if the requester later retries the request, it will | Thus, if the requester later retries the request, it will | |||
get NFS4ERR_RETRY_UNCACHED_REP. | get NFS4ERR_RETRY_UNCACHED_REP. | |||
If a replier receives a retried Sequence operation where the reply | If a replier receives a retried Sequence operation where the reply | |||
to the COMPOUND or CB_COMPOUND was not cached, then the replier, | to the COMPOUND or CB_COMPOUND was not cached, then the replier, | |||
<list style='symbols'> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <li> | |||
MAY return NFS4ERR_RETRY_UNCACHED_REP | <bcp14>MAY</bcp14> return NFS4ERR_RETRY_UNCACHED_REP | |||
in reply to a Sequence operation if the | in reply to a Sequence operation if the | |||
Sequence operation is not the first | Sequence operation is not the first | |||
operation (granted, a requester that | operation (granted, a requester that | |||
does so is in violation of the NFSv4.1 | does so is in violation of the NFSv4.1 | |||
protocol). | protocol). | |||
</t> | </li> | |||
<li> | ||||
<t> | <bcp14>MUST NOT</bcp14> return | |||
MUST NOT return | ||||
NFS4ERR_RETRY_UNCACHED_REP in reply to | NFS4ERR_RETRY_UNCACHED_REP in reply to | |||
a Sequence operation if the Sequence | a Sequence operation if the Sequence | |||
operation is the first operation. | operation is the first operation. | |||
</t> | </li> | |||
</ul> | ||||
</list> | </li> | |||
<li> | ||||
</t> | ||||
<t> | ||||
If the second operation is an illegal operation, or an | If the second operation is an illegal operation, or an | |||
operation that was legal in a previous minor version of | operation that was legal in a previous minor version of | |||
NFSv4 and MUST NOT | NFSv4 and <bcp14>MUST NOT</bcp14> | |||
be supported in the current minor version (e.g., SETCLIENTID), the | be supported in the current minor version (e.g., SETCLIENTID), the | |||
replier MUST NOT ever return NFS4ERR_RETRY_UNCACHED_REP. | replier <bcp14>MUST NOT</bcp14> ever return NFS4ERR_RETRY_UNCACHED_REP. | |||
Instead the replier MUST return NFS4ERR_OP_ILLEGAL or | Instead the replier <bcp14>MUST</bcp14> return NFS4ERR_OP_ILLEGAL or | |||
NFS4ERR_BADXDR or NFS4ERR_NOTSUPP as appropriate. | NFS4ERR_BADXDR or NFS4ERR_NOTSUPP as appropriate. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
If the second operation can result in another error status, | If the second operation can result in another error status, | |||
the replier MAY return a status other than NFS4ERR_RETRY_UNCACHED_REP, | the replier <bcp14>MAY</bcp14> return a status other than NFS4ERR_RETRY_ UNCACHED_REP, | |||
provided the operation is not executed in such a way that the state | provided the operation is not executed in such a way that the state | |||
of the replier is changed. Examples of such | of the replier is changed. Examples of such | |||
an error status include: NFS4ERR_NOTSUPP returned for an | an error status include: NFS4ERR_NOTSUPP returned for an | |||
operation that is legal but not REQUIRED in the current | operation that is legal but not <bcp14>REQUIRED</bcp14> in the current | |||
minor versions, and thus not supported by the replier; | minor versions, and thus not supported by the replier; | |||
NFS4ERR_SEQUENCE_POS; and NFS4ERR_REQ_TOO_BIG. | NFS4ERR_SEQUENCE_POS; and NFS4ERR_REQ_TOO_BIG. | |||
</t> | </li> | |||
</ul> | ||||
</list> | <t> | |||
</t> | ||||
<t> | ||||
The discussion above assumes that the | The discussion above assumes that the | |||
retried request matches the original | retried request matches the original | |||
one. <xref target="false_retry"/> | one. <xref target="false_retry" format="default"/> | |||
discusses what the replier might do, and | discusses what the replier might do, and | |||
MUST do when original and retried requests do not match. | <bcp14>MUST</bcp14> do when original and retried requests do not match. | |||
Since the replier may | Since the replier may | |||
only cache a small amount of the | only cache a small amount of the | |||
information that would be required to | information that would be required to | |||
determine whether this is a case of a | determine whether this is a case of a | |||
false retry, the replier may send to the | false retry, the replier may send to the | |||
client any of the following responses: | client any of the following responses: | |||
<list style='symbols'> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <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 matc h). | it in its entirety and the users of the original request and retry matc h). | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
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. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
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. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
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 origina l | NFS4_OK, together with the second operation as it appeared in the origina l | |||
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. | |||
</t> | </li> | |||
</list> | </ul> | |||
<section anchor="false_retry" numbered="true" toc="default"> | ||||
</t> | <name>False Retry</name> | |||
<t> | ||||
<section anchor="false_retry" title="False Retry"> | ||||
<t> | ||||
If a requester sent a Sequence operation | If a requester sent a Sequence operation | |||
with a slot ID and sequence ID that are | with a slot ID and sequence ID that are | |||
in the reply cache but the replier | in the reply cache but the replier | |||
detected that the retried request is not | detected that the retried request is not | |||
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 MUST 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 MUST NOT 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 MAY return | the replier <bcp14>MAY</bcp14> return | |||
NFS4ERR_FALSE_RETRY (and MUST 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 MAY 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 MUST NOT 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> <!-- Optional Reply Caching --> | </section> | |||
</section> <!-- Slot Identifiers and Server Reply Cache --> | ||||
<section anchor="Retry_and_Replay" title="Retry and Replay of Reply"> | <section anchor="Retry_and_Replay" numbered="true" toc="default"> | |||
<t> | <name>Retry and Replay of Reply</name> | |||
A requester MUST NOT retry a request, unless | <t> | |||
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. | |||
</t> | </t> | |||
<t> | <t> | |||
If the requester is a server wanting to re-send a callback | If the requester is a server wanting to re-send a callback | |||
operation over the backchannel of a session, the requester | operation over the backchannel of a session, the requester | |||
of course cannot reconnect because only the client can | of course cannot reconnect because only the client can | |||
associate connections with the backchannel. The | associate connections with the backchannel. The | |||
server can re-send the request over another connection that | server can re-send the request over another connection that | |||
is bound to the same session's backchannel. If there is no | is bound to the same session's backchannel. If there is no | |||
such connection, the server | such connection, the server | |||
MUST indicate that the session has no backchannel by setting | <bcp14>MUST</bcp14> indicate that the session has no backchannel by setting | |||
the SEQ4_STATUS_CB_PATH_DOWN_SESSION flag bit in the response | the SEQ4_STATUS_CB_PATH_DOWN_SESSION flag bit in the response | |||
to the next SEQUENCE operation from the client. The client MUST | to the next SEQUENCE operation from the client. The client <bcp14>MUST</bcp 14> | |||
then associate a connection with the session (or destroy | then associate a connection with the session (or destroy | |||
the session). | the session). | |||
</t> | </t> | |||
<t> | <t> | |||
Note that it is not fatal for a requester to retry | Note that it is not fatal for a requester to retry | |||
without a disconnect between the request and retry. | without a disconnect between the request and retry. | |||
However, the retry does consume resources, especially | However, the retry does consume resources, especially | |||
with RDMA, where each request, retry or not, consumes | with RDMA, where each request, retry or not, consumes | |||
a credit. Retries for no reason, especially retries | a credit. Retries for no reason, especially retries | |||
sent shortly after the previous attempt, are a poor | sent shortly after the previous attempt, are a poor | |||
use of network bandwidth and defeat the purpose of a | use of network bandwidth and defeat the purpose of a | |||
transport's inherent congestion control system. | transport's inherent congestion control system. | |||
</t> | </t> | |||
<t> | <t> | |||
A requester MUST wait for a reply to a request before using | A requester <bcp14>MUST</bcp14> wait for a reply to a request before using | |||
the slot for another request. If it does not wait for | the slot for another request. If it does not wait for | |||
a reply, then the requester does not know what | a reply, then the requester does not know what | |||
sequence ID to use for the slot on its next request. | sequence ID to use for the slot on its next request. | |||
For example, suppose a requester sends a request with sequence ID | For example, suppose a requester sends a request with sequence ID | |||
1, and does not wait for the response. The next time it uses | 1, and does not wait for the response. The next time it uses | |||
the slot, it sends the new request with sequence ID 2. | the slot, it sends the new request with sequence ID 2. | |||
If the replier has not seen the request with sequence ID 1, then | If the replier has not seen the request with sequence ID 1, then | |||
the replier is not expecting sequence ID 2, and rejects the | the replier is not expecting sequence ID 2, and rejects the | |||
requester's new request with NFS4ERR_SEQ_MISORDERED (as the | requester's new request with NFS4ERR_SEQ_MISORDERED (as the | |||
result from SEQUENCE or CB_SEQUENCE). | result from SEQUENCE or CB_SEQUENCE). | |||
</t> | </t> | |||
<t> | <t> | |||
RDMA fabrics do not guarantee that the memory handles | RDMA fabrics do not guarantee that the memory handles | |||
(Steering Tags) within each RPC/RDMA "chunk" <xref target="RFC8166" /> | (Steering Tags) within each RPC/RDMA "chunk" <xref target="RFC8166" format= "default"/> | |||
are valid on a scope | are valid on a scope | |||
outside that of a single connection. Therefore, handles used by | outside that of a single connection. Therefore, handles used by | |||
the direct operations become invalid after connection loss. The | the direct operations become invalid after connection loss. The | |||
server must ensure that any RDMA operations that must be replayed | server must ensure that any RDMA operations that must be replayed | |||
from the reply cache use the newly provided handle(s) from the | from the reply cache use the newly provided handle(s) from the | |||
most recent request. | most recent request. | |||
</t> | </t> | |||
<t> | <t> | |||
A retry might be sent while the original request is still in | A retry might be sent while the original request is still in | |||
progress on the replier. The replier SHOULD deal with the issue | progress on the replier. The replier <bcp14>SHOULD</bcp14> deal with the is sue | |||
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 MAY 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> <!-- Retry and Replay --> | ||||
<section anchor="sessions_callback_races" title="Resolving Server Callback R | <section anchor="sessions_callback_races" numbered="true" toc="default"> | |||
aces"> | <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 | |||
network. If a conflicting operation arrives at the | network. If a conflicting operation arrives at the | |||
server, it will recall the delegation using the | server, it will recall the delegation using the | |||
backchannel, which may be on a different | backchannel, which may be on a different | |||
transport connection, perhaps even a different | transport connection, perhaps even a different | |||
network, or even a different session associated with | network, or even a different session associated with | |||
the same client ID. | the same client ID. | |||
</t> | </t> | |||
<t> | <t> | |||
The presence of a session between the client and server | The presence of a session between the client and server | |||
alleviates this issue. When a session is in place, | alleviates this issue. When a session is in place, | |||
each client request is uniquely identified by its { | each client request is uniquely identified by its { | |||
session ID, slot ID, sequence ID } triple. By the rules under which | session ID, slot ID, sequence ID } triple. By the rules under which | |||
slot entries (reply cache entries) are | slot entries (reply cache entries) are | |||
retired, the server has knowledge whether the client | retired, the server has knowledge whether the client | |||
has "seen" each of the server's replies. The server | has "seen" each of the server's replies. The server | |||
can therefore provide sufficient information to the | can therefore provide sufficient information to the | |||
client to allow it to disambiguate between an | client to allow it to disambiguate between an | |||
erroneous or conflicting callback race | erroneous or conflicting callback race | |||
condition. | condition. | |||
</t> | </t> | |||
<t> | <t> | |||
For each client operation that might result in some | For each client operation that might result in some | |||
sort of server callback, the server SHOULD "remember" | sort of server callback, the server <bcp14>SHOULD</bcp14> "remember" | |||
the { session ID, slot ID, sequence ID } triple of the client request | the { session ID, slot ID, sequence ID } triple of the client request | |||
until the slot ID retirement rules allow the server to | until the slot ID retirement rules allow the server to | |||
determine that the client has, in fact, seen the | determine that the client has, in fact, seen the | |||
server's reply. Until the time the { session ID, slot ID, | server's reply. Until the time the { session ID, slot ID, | |||
sequence ID } request triple can be retired, any recalls | sequence ID } request triple can be retired, any recalls | |||
of the associated object MUST carry an array of these | of the associated object <bcp14>MUST</bcp14> carry an array of these | |||
referring identifiers (in the CB_SEQUENCE operation's | referring identifiers (in the CB_SEQUENCE operation's | |||
arguments), for the benefit of the client. After this | arguments), for the benefit of the client. After this | |||
time, it is not necessary for the server to provide | time, it is not necessary for the server to provide | |||
this information in related callbacks, since it is | this information in related callbacks, since it is | |||
certain that a race condition can no longer occur. | certain that a race condition can no longer occur. | |||
</t> | </t> | |||
<t> | <t> | |||
The CB_SEQUENCE operation that begins each server | The CB_SEQUENCE operation that begins each server | |||
callback carries a list of "referring" { session ID, slot ID, | callback carries a list of "referring" { session ID, slot ID, | |||
sequence ID } triples. If the client finds the request | sequence ID } triples. If the client finds the request | |||
corresponding to the referring session ID, slot ID, and sequence ID | corresponding to the referring session ID, slot ID, and sequence ID | |||
to be currently outstanding (i.e., the server's reply has | to be currently outstanding (i.e., the server's reply has | |||
not been seen by the client), it can determine that | not been seen by the client), it can determine that | |||
the callback has raced the reply, and act | the callback has raced the reply, and act | |||
accordingly. If the client does not find the request | accordingly. If the client does not find the request | |||
corresponding to the referring triple to be outstanding (including | corresponding to the referring triple to be outstanding (including | |||
the case of a session ID referring to a destroyed session), | the case of a session ID referring to a destroyed session), | |||
then there is no race with respect to this triple. | then there is no race with respect to this triple. | |||
The server SHOULD limit the referring triples | The server <bcp14>SHOULD</bcp14> limit the referring triples | |||
to requests that refer to just those that apply to the objects | to requests that refer to just those that apply to the objects | |||
referred to in | referred to in | |||
the CB_COMPOUND procedure. | the CB_COMPOUND procedure. | |||
</t> | </t> | |||
<t> | <t> | |||
The client must not simply wait forever for the | The client must not simply wait forever for the | |||
expected server reply to arrive before responding to the | expected server reply to arrive before responding to the | |||
CB_COMPOUND that won the race, | CB_COMPOUND that won the race, | |||
because it is possible | because it is possible | |||
that it will be delayed indefinitely. The client should | that it will be delayed indefinitely. The client should | |||
assume the likely case that the reply will arrive within | assume the likely case that the reply will arrive within | |||
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" />. | <xref target="pnfs_operation_sequencing" format="default"/>. | |||
</t> | </t> | |||
</section> <!-- Resolving server callback races with sessions --> | </section> | |||
<section anchor="COMPOUND_Sizing_Issues" title="COMPOUND and CB_COMPOUND Cons | <section anchor="COMPOUND_Sizing_Issues" numbered="true" toc="default"> | |||
truction Issues"> | <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" />), for each channel (fore and | (<xref target="OP_CREATE_SESSION" format="default"/>), for each channel (for e 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 | |||
they will return or process (ca_maxresponsesize), and the | they will return or process (ca_maxresponsesize), and the | |||
maximum-sized reply they will store in the reply cache | maximum-sized reply they will store in the reply cache | |||
(ca_maxresponsesize_cached). | (ca_maxresponsesize_cached). | |||
</t> | </t> | |||
<t> | <t> | |||
If a request exceeds ca_maxrequestsize, the reply will | If a request exceeds ca_maxrequestsize, the reply will | |||
have the status NFS4ERR_REQ_TOO_BIG. A replier MAY | have the status NFS4ERR_REQ_TOO_BIG. A replier <bcp14>MAY</bcp14> | |||
return NFS4ERR_REQ_TOO_BIG as the status for the first operation | return NFS4ERR_REQ_TOO_BIG as the status for the first operation | |||
(SEQUENCE or CB_SEQUENCE) in the request (which means that | (SEQUENCE or CB_SEQUENCE) in the request (which means that | |||
no operations in the request executed and that the | no operations in the request executed and that the | |||
state of the slot in the reply cache is unchanged), or it MAY | state of the slot in the reply cache is unchanged), or it <bcp14>MAY</bcp14> | |||
opt to return it on a subsequent operation in the same | opt to return it on a subsequent operation in the same | |||
COMPOUND or CB_COMPOUND request (which means that at least one | COMPOUND or CB_COMPOUND request (which means that at least one | |||
operation did execute and that the state of the slot in the reply cache does | operation did execute and that the state of the slot in the reply cache does | |||
change). The replier SHOULD set NFS4ERR_REQ_TOO_BIG on the | change). The replier <bcp14>SHOULD</bcp14> set NFS4ERR_REQ_TOO_BIG on the | |||
operation that exceeds ca_maxrequestsize. | operation that exceeds ca_maxrequestsize. | |||
</t> | </t> | |||
<t> | <t> | |||
If a reply exceeds ca_maxresponsesize, the reply will | If a reply exceeds ca_maxresponsesize, the reply will | |||
have the status NFS4ERR_REP_TOO_BIG. A replier MAY | have the status NFS4ERR_REP_TOO_BIG. A replier <bcp14>MAY</bcp14> | |||
return NFS4ERR_REP_TOO_BIG as the status for the first operation | return NFS4ERR_REP_TOO_BIG as the status for the first operation | |||
(SEQUENCE or CB_SEQUENCE) in the request, or it MAY | (SEQUENCE or CB_SEQUENCE) in the request, or it <bcp14>MAY</bcp14> | |||
opt to return it on a subsequent operation (in the same | opt to return it on a subsequent operation (in the same | |||
COMPOUND or CB_COMPOUND reply). A replier MAY return NFS4ERR_REP_TOO_BIG | COMPOUND or CB_COMPOUND reply). A replier <bcp14>MAY</bcp14> return NFS4ERR_ REP_TOO_BIG | |||
in the reply to SEQUENCE or CB_SEQUENCE, even if the response | in the reply to SEQUENCE or CB_SEQUENCE, even if the response | |||
would still exceed ca_maxresponsesize. | would still exceed ca_maxresponsesize. | |||
</t> | </t> | |||
<t> | <t> | |||
If sa_cachethis or csa_cachethis is TRUE, then the | If sa_cachethis or csa_cachethis is TRUE, then the | |||
replier MUST cache a reply except if an error is | replier <bcp14>MUST</bcp14> cache a reply except if an error is | |||
returned by the SEQUENCE or CB_SEQUENCE operation (see | returned by the SEQUENCE or CB_SEQUENCE operation (see | |||
<xref target="err_sequence" />). If the reply exceeds | <xref target="err_sequence" format="default"/>). If the reply exceeds | |||
ca_maxresponsesize_cached (and sa_cachethis or | ca_maxresponsesize_cached (and sa_cachethis or | |||
csa_cachethis is TRUE), then the server MUST return | csa_cachethis is TRUE), then the server <bcp14>MUST</bcp14> return | |||
NFS4ERR_REP_TOO_BIG_TO_CACHE. Even if | NFS4ERR_REP_TOO_BIG_TO_CACHE. Even if | |||
NFS4ERR_REP_TOO_BIG_TO_CACHE (or any other error for | NFS4ERR_REP_TOO_BIG_TO_CACHE (or any other error for | |||
that matter) is returned on an operation other than the | that matter) is returned on an operation other than the | |||
first operation (SEQUENCE or CB_SEQUENCE), then | first operation (SEQUENCE or CB_SEQUENCE), then | |||
the reply MUST be cached if sa_cachethis or | the reply <bcp14>MUST</bcp14> be cached if sa_cachethis or | |||
csa_cachethis is TRUE. | csa_cachethis is TRUE. | |||
For example, if a COMPOUND has eleven | For example, if a COMPOUND has eleven | |||
operations, including SEQUENCE, the fifth operation is | operations, including SEQUENCE, the fifth operation is | |||
a RENAME, and the tenth operation is a READ for one | a RENAME, and the tenth operation is a READ for one | |||
million bytes, the server may return | million bytes, the server may return | |||
NFS4ERR_REP_TOO_BIG_TO_CACHE on the tenth operation. | NFS4ERR_REP_TOO_BIG_TO_CACHE on the tenth operation. | |||
Since the server executed several operations, especially | Since the server executed several operations, especially | |||
the non-idempotent RENAME, the client's request to | the non-idempotent RENAME, the client's request to | |||
cache the reply needs to be honored in order for the | cache the reply needs to be honored in order for the | |||
correct operation of exactly once semantics. If the | correct operation of exactly once semantics. If the | |||
client retries the request, the server will have cached | client retries the request, the server will have cached | |||
a reply that contains results for ten of the eleven requested | a reply that contains results for ten of the eleven requested | |||
operations, with | operations, with | |||
the tenth operation having a status of NFS4ERR_REP_TOO_BIG_TO_CACHE. | the tenth operation having a status of NFS4ERR_REP_TOO_BIG_TO_CACHE. | |||
</t> | </t> | |||
<t> | <t> | |||
A client needs to take care that, when sending | A client needs to take care that, when sending | |||
operations that change the current filehandle (except for | operations that change the current filehandle (except for | |||
PUTFH, PUTPUBFH, PUTROOTFH, and RESTOREFH), it | PUTFH, PUTPUBFH, PUTROOTFH, and RESTOREFH), it | |||
does not exceed the maximum reply buffer before the GETFH | does not exceed the maximum reply buffer before the GETFH | |||
operation. Otherwise, the client will have to retry | operation. Otherwise, the client will have to retry | |||
the operation that changed the current filehandle, in order | the operation that changed the current filehandle, in order | |||
to obtain the desired filehandle. | to obtain the desired filehandle. | |||
For the OPEN operation (see <xref target="OP_OPEN" />), | For the OPEN operation (see <xref target="OP_OPEN" format="default"/>), | |||
retry is not always available as an option. | retry is not always available as an option. | |||
The following guidelines for the handling of | The following guidelines for the handling of | |||
filehandle-changing operations are advised: | filehandle-changing operations are advised: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Within the same COMPOUND procedure, a client | Within the same COMPOUND procedure, a client | |||
SHOULD send GETFH immediately after a current | <bcp14>SHOULD</bcp14> send GETFH immediately after a current | |||
filehandle-changing operation. A client | filehandle-changing operation. A client | |||
MUST send GETFH after a current filehandle-changing operation | <bcp14>MUST</bcp14> send GETFH after a current filehandle-changing operatio n | |||
that is also non-idempotent (e.g., the OPEN operation), unless | that is also non-idempotent (e.g., the OPEN operation), unless | |||
the operation is RESTOREFH. RESTOREFH is | the operation is RESTOREFH. RESTOREFH is | |||
an exception, because even though it is | an exception, because even though it is | |||
non-idempotent, the filehandle RESTOREFH | non-idempotent, the filehandle RESTOREFH | |||
produced originated from an operation that | produced originated from an operation that | |||
is either idempotent (e.g., PUTFH, LOOKUP), | is either idempotent (e.g., PUTFH, LOOKUP), | |||
or non-idempotent (e.g., OPEN, CREATE). If the | or non-idempotent (e.g., OPEN, CREATE). If the | |||
origin is non-idempotent, then because the client | origin is non-idempotent, then because the client | |||
MUST send GETFH after the origin operation, the | <bcp14>MUST</bcp14> send GETFH after the origin operation, the | |||
client can recover if RESTOREFH returns an error. | client can recover if RESTOREFH returns an error. | |||
</t> | </li> | |||
<t> | <li> | |||
A server MAY return NFS4ERR_REP_TOO_BIG or | A server <bcp14>MAY</bcp14> return NFS4ERR_REP_TOO_BIG or | |||
NFS4ERR_REP_TOO_BIG_TO_CACHE (if sa_cachethis is TRUE) | NFS4ERR_REP_TOO_BIG_TO_CACHE (if sa_cachethis is TRUE) | |||
on a filehandle-changing operation if the reply would | on a filehandle-changing operation if the reply would | |||
be too large on the next operation. | be too large on the next operation. | |||
</t> | </li> | |||
<t> | <li> | |||
A server SHOULD return NFS4ERR_REP_TOO_BIG or | A server <bcp14>SHOULD</bcp14> return NFS4ERR_REP_TOO_BIG or | |||
NFS4ERR_REP_TOO_BIG_TO_CACHE (if sa_cachethis is TRUE) | NFS4ERR_REP_TOO_BIG_TO_CACHE (if sa_cachethis is TRUE) | |||
on a filehandle-changing, non-idempotent operation if the reply would | on a filehandle-changing, non-idempotent operation if the reply would | |||
be too large on the next operation, especially if the operation | be too large on the next operation, especially if the operation | |||
is OPEN. | is OPEN. | |||
</t> | </li> | |||
<t> | <li> | |||
A server MAY return NFS4ERR_UNSAFE_COMPOUND to a non-idempotent | A server <bcp14>MAY</bcp14> return NFS4ERR_UNSAFE_COMPOUND to a non-idempot | |||
ent | ||||
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 SHOULD 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. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> <!-- COMPOUND and CB_COMPOUND Construction Issues --> | <section anchor="Persistence" numbered="true" toc="default"> | |||
<section anchor="Persistence" title="Persistence"> | <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 MUST 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" />): | was created; see <xref target="OP_CREATE_SESSION" format="default"/>): | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The session ID. | The session ID. | |||
</t> | </li> | |||
<t> | <li> | |||
The slot table including the sequence ID and cached reply for | The slot table including the sequence ID and cached reply for | |||
each slot. | each slot. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
The above are sufficient for a replier to provide EOS semantics | The above are sufficient for a replier to provide EOS semantics | |||
for any requests that were sent and executed before the server | for any requests that were sent and executed before the server | |||
restarted. | restarted. | |||
If the replier is a client, then there is no need for | If the replier is a client, then there is no need for | |||
it to persist any more information, unless the client will | it to persist any more information, unless the client will | |||
be persisting all other state across client restart, in which case, | be persisting all other state across client restart, in which case, | |||
the server will never see any NFSv4.1-level protocol manifestation | the server will never see any NFSv4.1-level protocol manifestation | |||
of a client restart. | of a client restart. | |||
If the replier is a server, with just the | If the replier is a server, with just the | |||
slot table and session ID persisting, | slot table and session ID persisting, | |||
any requests the client retries after the server restart will | any requests the client retries after the server restart will | |||
return the results that are cached in the reply cache, | return the results that are cached in the reply cache, | |||
and any new requests (i.e., the sequence ID is one greater than the | and any new requests (i.e., the sequence ID is one greater than the | |||
slot's sequence ID) MUST be rejected with NFS4ERR_DEADSESSION | slot's sequence ID) <bcp14>MUST</bcp14> be rejected with NFS4ERR_DEADSESSION | |||
(returned by SEQUENCE). Such a session is considered dead. | (returned by SEQUENCE). Such a session is considered dead. | |||
A server MAY re-animate a session | A server <bcp14>MAY</bcp14> re-animate a session | |||
after a server restart so that the session will accept new | after a server restart so that the session will accept new | |||
requests as well as retries. To re-animate a session, | requests as well as retries. To re-animate a session, | |||
the server needs to persist additional information | the server needs to persist additional information | |||
through server restart: | through server restart: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The client ID. This is a prerequisite to let the client | The client ID. This is a prerequisite to let the client | |||
create more sessions associated with the same client ID | create more sessions associated with the same client ID | |||
as the re-animated session. | as the re-animated session. | |||
</t> | </li> | |||
<t> | <li> | |||
The client ID's sequence ID that is used for creating | The client ID's sequence ID that is used for creating | |||
sessions (see Sections <xref target="OP_EXCHANGE_ID" format="counter" /> an | sessions (see Sections <xref target="OP_EXCHANGE_ID" format="counter"/> and | |||
d | <xref target="OP_CREATE_SESSION" format="counter"/>). This is a | |||
<xref target="OP_CREATE_SESSION" format="counter" />). This is a | ||||
prerequisite to let the client create more sessions. | prerequisite to let the client create more sessions. | |||
</t> | </li> | |||
<t> | <li> | |||
The principal that created the client ID. This | The principal that created the client ID. This | |||
allows the server to authenticate the client when | allows the server to authenticate the client when | |||
it sends EXCHANGE_ID. | it sends EXCHANGE_ID. | |||
</t> | </li> | |||
<t> | <li> | |||
The SSV, if SP4_SSV state protection was | The SSV, if SP4_SSV state protection was | |||
specified when the client ID was created (see <xref | specified when the client ID was created (see <xref target="OP_EXCHANGE_ID" | |||
target="OP_EXCHANGE_ID" />). This lets the | format="default"/>). This lets the | |||
client create new sessions, and associate connections | client create new sessions, and associate connections | |||
with the new and existing sessions. | with the new and existing sessions. | |||
</t> | </li> | |||
<t> | <li> | |||
The properties of the client ID as defined in | The properties of the client ID as defined in | |||
<xref target="OP_EXCHANGE_ID" />. | <xref target="OP_EXCHANGE_ID" format="default"/>. | |||
</t> | </li> | |||
</ul> | ||||
</list> | <t> | |||
</t> | ||||
<t> | ||||
A persistent reply cache places certain demands on the server. | A persistent reply cache places certain demands on the server. | |||
The execution of the sequence of operations (starting with SEQUENCE) | The execution of the sequence of operations (starting with SEQUENCE) | |||
and placement of its results in the persistent cache MUST be atomic. If | and placement of its results in the persistent cache <bcp14>MUST</bcp14> be atomic. If | |||
a client retries a sequence of operations that was previously | a client retries a sequence of operations that was previously | |||
executed on the server, the only acceptable outcomes are either | executed on the server, the only acceptable outcomes are either | |||
the original cached reply or an indication that the client ID | the original cached reply or an indication that the client ID | |||
or session has been lost (indicating a catastrophic loss | or session has been lost (indicating a catastrophic loss | |||
of the reply cache or a session that has been deleted because | of the reply cache or a session that has been deleted because | |||
the client failed to use the session for an extended period | the client failed to use the session for an extended period | |||
of time). | of time). | |||
</t> | </t> | |||
<t> | <t> | |||
A server could fail and restart in the middle of a | A server could fail and restart in the middle of a | |||
COMPOUND procedure that contains one or more non-idempotent | COMPOUND procedure that contains one or more non-idempotent | |||
or idempotent-but-modifying operations. This creates | or idempotent-but-modifying operations. This creates | |||
an even higher challenge for atomic execution and | an even higher challenge for atomic execution and | |||
placement of results in the reply cache. One way | placement of results in the reply cache. One way | |||
to view the problem is as a single transaction consisting of | to view the problem is as a single transaction consisting of | |||
each operation in the COMPOUND followed by storing | each operation in the COMPOUND followed by storing | |||
the result in persistent storage, then finally a transaction | the result in persistent storage, then finally a transaction | |||
commit. If there is a failure before the transaction | commit. If there is a failure before the transaction | |||
is committed, then the server rolls back the transaction. | is committed, then the server rolls back the transaction. | |||
If the server itself fails, then when it restarts, its | If the server itself fails, then when it restarts, its | |||
recovery logic could roll back the transaction | recovery logic could roll back the transaction | |||
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"/> is described in <xref target="ha_nfs_ibm" | for NFSv2 <xref target="RFC1094" format="default"/> is described in <xref ta | |||
/>. | rget="ha_nfs_ibm" format="default"/>. | |||
</t> | </t> | |||
</section> <!-- Persistence --> | </section> | |||
</section> <!-- Exactly Once Semantics --> | </section> | |||
<section anchor="RDMA_Considerations" title="RDMA Considerations"> | <section anchor="RDMA_Considerations" numbered="true" toc="default"> | |||
<t> | <name>RDMA Considerations</name> | |||
<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" />. 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" />. Where RDMA is considered, | over RDMA is in <xref target="RFC8267" format="default"/>. Where RDMA is con sidered, | |||
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. | |||
</t> | </t> | |||
<section anchor="RDMA_Connection_Resources" title="RDMA Connection Resources" | <section anchor="RDMA_Connection_Resources" numbered="true" toc="defau | |||
> | lt"> | |||
<t> | <name>RDMA Connection Resources</name> | |||
<t> | ||||
RDMA requires its consumers to register memory and post | RDMA requires its consumers to register memory and post | |||
buffers of a specific size and number for receive | buffers of a specific size and number for receive | |||
operations. | operations. | |||
</t> | </t> | |||
<t> | <t> | |||
Registration of memory can be a relatively high-overhead operation, | Registration of memory can be a relatively high-overhead operation, | |||
since it requires pinning of buffers, assignment of attributes | since it requires pinning of buffers, assignment of attributes | |||
(e.g., readable/writable), and initialization of hardware | (e.g., readable/writable), and initialization of hardware | |||
translation. Preregistration is desirable to reduce overhead. | translation. Preregistration is desirable to reduce overhead. | |||
These registrations are specific to hardware interfaces and even to | These registrations are specific to hardware interfaces and even to | |||
RDMA connection endpoints; therefore, negotiation of their limits is | RDMA connection endpoints; therefore, negotiation of their limits is | |||
desirable to manage resources effectively. | desirable to manage resources effectively. | |||
</t> | </t> | |||
<t> | <t> | |||
Following basic registration, these buffers must be posted by | Following basic registration, these buffers must be posted by | |||
the RPC layer to handle receives. These buffers remain in use by | the RPC layer to handle receives. These buffers remain in use by | |||
the RPC/NFSv4.1 implementation; the size and number of them must be | the RPC/NFSv4.1 implementation; the size and number of them must be | |||
known to the remote peer in order to avoid RDMA errors that would | known to the remote peer in order to avoid RDMA errors that would | |||
cause a fatal error on the RDMA connection. | cause a fatal error on the RDMA connection. | |||
</t> | </t> | |||
<t> | <t> | |||
NFSv4.1 manages slots as resources on a per-session | NFSv4.1 manages slots as resources on a per-session | |||
basis (see <xref target="Session" />), while RDMA | basis (see <xref target="Session" format="default"/>), while RDMA | |||
connections manage credits on a per-connection basis. | connections manage credits on a per-connection basis. | |||
This means that in order for a peer to send data over | This means that in order for a peer to send data over | |||
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> <!-- RDMA Connection Resources --> | </section> | |||
<section anchor="Flow_Control" title="Flow Control"> | <section anchor="Flow_Control" numbered="true" toc="default"> | |||
<t> | <name>Flow Control</name> | |||
<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. | |||
Limits such as maximum number of requests | Limits such as maximum number of requests | |||
outstanding are therefore negotiated when a session | outstanding are therefore negotiated when a session | |||
is created (see the ca_maxrequests field in <xref | is created (see the ca_maxrequests field in <xref target="OP_CREATE_SESSION" | |||
target="OP_CREATE_SESSION" />). These limits then | format="default"/>). These limits then | |||
provide the maxima within which each connection associated | provide the maxima within which each connection associated | |||
with the session's channel(s) must remain. | with the session's channel(s) must remain. | |||
RDMA connections are managed within these limits as | RDMA connections are managed within these limits as | |||
described in Section 3.3 of <xref target="RFC8166" />; if there are multiple | described in <xref target="RFC8166" sectionFormat="of" section="3.3"/>; if t here are multiple | |||
RDMA connections, then the maximum number of requests | RDMA connections, then the maximum number of requests | |||
for a channel will be divided among the RDMA | for a channel will be divided among the RDMA | |||
connections. Put a different way, the onus is on the | connections. Put a different way, the onus is on the | |||
replier to ensure that the total number of RDMA credits | replier to ensure that the total number of RDMA credits | |||
across all connections associated with the replier's | across all connections associated with the replier's | |||
channel does exceed the channel's maximum number of | channel does exceed the channel's maximum number of | |||
outstanding requests. | outstanding requests. | |||
</t> | </t> | |||
<t> | <t> | |||
The limits may also be modified | The limits may also be modified | |||
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" />) 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> <!-- Flow Control --> | </section> | |||
<section anchor="Padding" title="Padding"> | <section anchor="Padding" numbered="true" toc="default"> | |||
<t> | <name>Padding</name> | |||
<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" />), and | <xref target="OP_CREATE_SESSION" format="default"/>), and | |||
subsequently used by the RPC RDMA layer, as described in <xref target="R | subsequently used by the RPC RDMA layer, as described in <xref target="R | |||
FC8166" />. | FC8166" format="default"/>. | |||
Zero padding is permitted. | Zero padding is permitted. | |||
</t> | </t> | |||
<t> | <t> | |||
Padding leverages the useful property | Padding leverages the useful property | |||
that RDMA preserve alignment of data, even when they are | that RDMA preserve alignment of data, even when they are | |||
placed into anonymous (untagged) buffers. If requested, client | placed into anonymous (untagged) buffers. If requested, client | |||
inline writes will insert appropriate pad bytes within the request | inline writes will insert appropriate pad bytes within the request | |||
header to align the data payload on the specified boundary. The | header to align the data payload on the specified boundary. The | |||
client is encouraged to add sufficient padding (up to the | client is encouraged to add sufficient padding (up to the | |||
negotiated size) so that | negotiated size) so that | |||
the "data" field of the WRITE operation | the "data" field of the WRITE operation | |||
is aligned. | is aligned. | |||
Most servers can make good use of such padding, | Most servers can make good use of such padding, | |||
which allows them to chain receive buffers in such a way that any | which allows them to chain receive buffers in such a way that any | |||
data carried by client requests will be placed into appropriate | data carried by client requests will be placed into appropriate | |||
buffers at the server, ready for file system processing. The | buffers at the server, ready for file system processing. The | |||
receiver's RPC layer encounters no overhead from skipping over pad | receiver's RPC layer encounters no overhead from skipping over pad | |||
bytes, and the RDMA layer's high performance makes the insertion | bytes, and the RDMA layer's high performance makes the insertion | |||
and transmission of padding on the sender a significant | and transmission of padding on the sender a significant | |||
optimization. In this way, the need for servers to perform RDMA | optimization. In this way, the need for servers to perform RDMA | |||
Read to satisfy all but the largest client writes is obviated. An | Read to satisfy all but the largest client writes is obviated. An | |||
added benefit is the reduction of message round trips on the network | added benefit is the reduction of message round trips on the network | |||
-- a potentially good trade, where latency is present. | -- a potentially good trade, where latency is present. | |||
</t> | </t> | |||
<t> | <t> | |||
The value to choose for padding is subject to a number of criteria. | The value to choose for padding is subject to a number of criteria. | |||
A primary source of variable-length data in the RPC header is the | A primary source of variable-length data in the RPC header is the | |||
authentication information, the form of which is client-determined, | authentication information, the form of which is client-determined, | |||
possibly in response to server specification. The contents of | possibly in response to server specification. The contents of | |||
COMPOUNDs, sizes of strings such as those passed to RENAME, etc. all | COMPOUNDs, sizes of strings such as those passed to RENAME, etc. all | |||
go into the determination of a maximal NFSv4.1 request size and | go into the determination of a maximal NFSv4.1 request size and | |||
therefore minimal buffer size. The client must select its offered | therefore minimal buffer size. The client must select its offered | |||
value carefully, so as to avoid overburdening the server, and vice | value carefully, so as to avoid overburdening the server, and vice | |||
versa. The benefit of an appropriate padding value is higher | versa. The benefit of an appropriate padding value is higher | |||
performance. | performance. | |||
</t> | </t> | |||
<figure> | <artwork name="" type="" align="left" alt=""><![CDATA[ | |||
<artwork> | ||||
Sender gather: | Sender gather: | |||
|RPC Request|Pad bytes|Length| -> |User data...| | |RPC Request|Pad bytes|Length| -> |User data...| | |||
\------+----------------------/ \ | \------+----------------------/ \ | |||
\ \ | \ \ | |||
\ Receiver scatter: \-----------+- ... | \ Receiver scatter: \-----------+- ... | |||
/-----+----------------\ \ \ | /-----+----------------\ \ \ | |||
|RPC Request|Pad|Length| -> |FS buffer|->|FS buffer|->... | |RPC Request|Pad|Length| -> |FS buffer|->|FS buffer|->... | |||
</artwork> | ]]></artwork> | |||
</figure> | <t> | |||
<t> | ||||
In the above case, the server may recycle unused buffers to the | In the above case, the server may recycle unused buffers to the | |||
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> <!-- Padding --> | </section> | |||
<section anchor="dual" title="Dual RDMA and Non-RDMA Transports"> | <section anchor="dual" numbered="true" toc="default"> | |||
<t> | <name>Dual RDMA and Non-RDMA Transports</name> | |||
Some RDMA transports (e.g., <xref target="RDMAP">RFC 5040</xref>) | <t> | |||
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> <!-- RDMA Transports --> | </section> | |||
</section> <!-- RDMA Considerations --> | </section> | |||
<section anchor="Sessions_Security" title="Session Security"> | <section anchor="Sessions_Security" numbered="true" toc="default"> | |||
<section anchor="Session_Callback_Security" title="Session Callback Security" | <name>Session Security</name> | |||
> | <section anchor="Session_Callback_Security" numbered="true" toc="defau | |||
<t> | lt"> | |||
<name>Session Callback Security</name> | ||||
<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" />) and subject to the same | <xref target="OP_BIND_CONN_TO_SESSION" format="default"/>) and subject to th e 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" />), | 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" />). | 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" />). | (see <xref target="Backchannel_RPC_Security" format="default"/>). | |||
</t> | </t> | |||
</section> <!-- Session Callback Security --> | </section> | |||
<section anchor="Backchannel_RPC_Security" title="Backchannel RPC Security"> | <section anchor="Backchannel_RPC_Security" numbered="true" toc="default"> | |||
<t> | <name>Backchannel RPC Security</name> | |||
<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 MUST NOT use unoffered combinations. | offers, but it <bcp14>MUST NOT</bcp14> use unoffered combinations. | |||
This way, the client need not provide a target | This way, the client need not provide a target | |||
GSS principal for the backchannel as it did with | GSS principal for the backchannel as it did with | |||
NFSv4.0, nor does the server have to implement an | NFSv4.0, nor does the server have to implement an | |||
RPCSEC_GSS initiator as it did with NFSv4.0 <xref | RPCSEC_GSS initiator as it did with NFSv4.0 <xref target="RFC3530" format=" | |||
target="RFC3530" />. | default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
The CREATE_SESSION (<xref target="OP_CREATE_SESSION" />) | The CREATE_SESSION (<xref target="OP_CREATE_SESSION" format="default"/>) | |||
and BACKCHANNEL_CTL (<xref target="OP_BACKCHANNEL_CTL" />) | 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 | (see Sections <xref target="OP_EXCHANGE_ID" format="counter"/> and <xref ta | |||
target="protect_state_change" format="counter" />) has the side | rget="protect_state_change" format="counter"/>) has the side | |||
benefit of providing SSV-derived RPCSEC_GSS contexts (<xref target="ssv_mec | benefit of providing SSV-derived RPCSEC_GSS contexts (<xref target="ssv_mec | |||
h" />). | h" format="default"/>). | |||
</t> | </t> | |||
</section> <!-- Backchannel RPC Security --> | </section> | |||
<section anchor="protect_state_change" | <section anchor="protect_state_change" numbered="true" toc="default"> | |||
title="Protection from Unauthorized State Changes"> | <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 | |||
disrupts the legitimate client and thus denies service to it. | disrupts the legitimate client and thus denies service to it. | |||
Similarly, an attacker could send a CREATE_SESSION with a forged | Similarly, an attacker could send a CREATE_SESSION with a forged | |||
client ID to create a new session associated with the client ID. | client ID to create a new session associated with the client ID. | |||
The attacker could send requests using the new session that | The attacker could send requests using the new session that | |||
change locking state, such as LOCKU operations to release locks | change locking state, such as LOCKU operations to release locks | |||
the legitimate client has acquired. Setting a security | the legitimate client has acquired. Setting a security | |||
policy on the file that requires RPCSEC_GSS credentials when | policy on the file that requires RPCSEC_GSS credentials when | |||
manipulating the file's state is one potential work around, | manipulating the file's state is one potential work around, | |||
but has the disadvantage of preventing a legitimate client from | but has the disadvantage of preventing a legitimate client from | |||
releasing state when RPCSEC_GSS is required to do so, but | releasing state when RPCSEC_GSS is required to do so, but | |||
a GSS context cannot be obtained (possibly because the user | a GSS context cannot be obtained (possibly because the user | |||
has logged off the client). | has logged off the client). | |||
</t> | </t> | |||
<t> | <t> | |||
NFSv4.1 provides three options to a client for state protection, | NFSv4.1 provides three options to a client for state protection, | |||
which are specified when a client creates | which are specified when a client creates | |||
a client ID via EXCHANGE_ID (<xref target="OP_EXCHANGE_ID" />). | a client ID via EXCHANGE_ID (<xref target="OP_EXCHANGE_ID" format="default" | |||
</t> | />). | |||
<t> | </t> | |||
<t> | ||||
The first (SP4_NONE) is to simply waive state protection. | The first (SP4_NONE) is to simply waive state protection. | |||
</t> | </t> | |||
<t> | <t> | |||
The other two options (SP4_MACH_CRED and SP4_SSV) | The other two options (SP4_MACH_CRED and SP4_SSV) | |||
share several traits: | share several traits: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
An RPCSEC_GSS-based credential is used to authenticate | An RPCSEC_GSS-based credential is used to authenticate | |||
client ID and session maintenance operations, | client ID and session maintenance operations, | |||
including creating and destroying a session, | including creating and destroying a session, | |||
associating a connection with the session, and | associating a connection with the session, and | |||
destroying the client ID. | destroying the client ID. | |||
</t> | </li> | |||
<t> | <li> | |||
Because RPCSEC_GSS is used to authenticate | Because RPCSEC_GSS is used to authenticate | |||
client ID and session maintenance, the attacker cannot | client ID and session maintenance, the attacker cannot | |||
associate a rogue connection with a legitimate session, or | associate a rogue connection with a legitimate session, or | |||
associate a rogue session with a legitimate client ID in | associate a rogue session with a legitimate client ID in | |||
order to maliciously alter the client ID's lock state | order to maliciously alter the client ID's lock state | |||
via CLOSE, LOCKU, DELEGRETURN, LAYOUTRETURN, etc. | via CLOSE, LOCKU, DELEGRETURN, LAYOUTRETURN, etc. | |||
</t> | </li> | |||
<t> | <li> | |||
In cases where the server's security policies on a | In cases where the server's security policies on a | |||
portion of its namespace require RPCSEC_GSS authentication, | portion of its namespace require RPCSEC_GSS authentication, | |||
a client may have to use an RPCSEC_GSS credential | a client may have to use an RPCSEC_GSS credential | |||
to remove per-file state (e.g., LOCKU, CLOSE, etc.). | to remove per-file state (e.g., LOCKU, CLOSE, etc.). | |||
The server may require that the principal that removes | The server may require that the principal that removes | |||
the state match certain criteria (e.g., | the state match certain criteria (e.g., | |||
the principal might have to be the same as the one | the principal might have to be the same as the one | |||
that acquired the state). However, the client might | that acquired the state). However, the client might | |||
not have an RPCSEC_GSS context for such a principal, | not have an RPCSEC_GSS context for such a principal, | |||
and might not be able to create such a context (perhaps | and might not be able to create such a context (perhaps | |||
because the user has logged off). When the client | because the user has logged off). When the client | |||
establishes SP4_MACH_CRED or SP4_SSV protection, | establishes SP4_MACH_CRED or SP4_SSV protection, | |||
it can specify a list of operations that the server MUST | it can specify a list of operations that the server <bcp14>MUST</bcp14> | |||
allow using the machine credential (if SP4_MACH_CRED | allow using the machine credential (if SP4_MACH_CRED | |||
is used) or the SSV credential (if SP4_SSV is used). | is used) or the SSV credential (if SP4_SSV is used). | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The SP4_MACH_CRED state protection option uses a machine | The SP4_MACH_CRED state protection option uses a machine | |||
credential where the principal that | credential where the principal that | |||
creates the client ID MUST also be the principal | creates the client ID <bcp14>MUST</bcp14> also be the principal | |||
that performs client ID and session maintenance | that performs client ID and session maintenance | |||
operations. | operations. | |||
The security of the machine credential state protection approach | The security of the machine credential state protection approach | |||
depends entirely on safeguarding the per-machine credential. | depends entirely on safeguarding the per-machine credential. | |||
Assuming a proper safeguard using the per-machine credential | Assuming a proper safeguard using the per-machine credential | |||
for operations like CREATE_SESSION, BIND_CONN_TO_SESSION, | for operations like CREATE_SESSION, BIND_CONN_TO_SESSION, | |||
DESTROY_SESSION, and DESTROY_CLIENTID will prevent an attacker | DESTROY_SESSION, and DESTROY_CLIENTID will prevent an attacker | |||
from associating a rogue connection with a session, or | from associating a rogue connection with a session, or | |||
associating a rogue session with a client ID. | associating a rogue session with a client ID. | |||
</t> | </t> | |||
<t> | <t> | |||
There are at least three scenarios for the SP4_MACH_CRED | There are at least three scenarios for the SP4_MACH_CRED | |||
option: | option: | |||
<list style="numbers"> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
The system administrator configures a unique, | The system administrator configures a unique, | |||
permanent per-machine credential for one of the | permanent per-machine credential for one of the | |||
mandated GSS mechanisms (e.g., if Kerberos | mandated GSS mechanisms (e.g., if Kerberos | |||
V5 is used, a "keytab" containing a principal derived from a | V5 is used, a "keytab" containing a principal derived from a | |||
client host name could be used). | client host name could be used). | |||
</t> | </li> | |||
<t> | <li> | |||
The client is used by a single user, and so the | The client is used by a single user, and so the | |||
client ID and its sessions are used by just that | client ID and its sessions are used by just that | |||
user. If the user's credential expires, then session | user. If the user's credential expires, then session | |||
and client ID maintenance cannot occur, but since | and client ID maintenance cannot occur, but since | |||
the client has a single user, only that user is | the client has a single user, only that user is | |||
inconvenienced. | inconvenienced. | |||
</t> | </li> | |||
<t> | <li> | |||
The physical client has multiple users, but the | The physical client has multiple users, but the | |||
client implementation has a unique client ID for | client implementation has a unique client ID for | |||
each user. This is effectively the same as the | each user. This is effectively the same as the | |||
second scenario, but a disadvantage is that each | second scenario, but a disadvantage is that each | |||
user needs to be allocated at least one session each, | user needs to be allocated at least one session each, | |||
so the approach suffers from lack of economy. | so the approach suffers from lack of economy. | |||
</t> | </li> | |||
</ol> | ||||
</list> | <t> | |||
</t> | The SP4_SSV protection option uses the SSV (<xref target="intro_definitions | |||
<t> | " format="default"/>), via RPCSEC_GSS and the SSV GSS | |||
The SP4_SSV protection option uses the SSV (<xref | mechanism (<xref target="ssv_mech" format="default"/>), to protect state fr | |||
target="intro_definitions"/>), via RPCSEC_GSS and the SSV GSS | om attack. | |||
mechanism (<xref target="ssv_mech" />), to protect state from attack. | ||||
The SP4_SSV protection option is intended for the situation | The SP4_SSV protection option is intended for the situation | |||
comprised of a client that has multiple active users and a system | comprised of a client that has multiple active users and a system | |||
administrator who wants to avoid the burden of installing a permanent | administrator who wants to avoid the burden of installing a permanent | |||
machine credential on each client. The SSV is | machine credential on each client. The SSV is | |||
established and updated on the server via SET_SSV (see <xref | established and updated on the server via SET_SSV (see <xref target="OP_SET | |||
target="OP_SET_SSV" />). To prevent eavesdropping, | _SSV" format="default"/>). To prevent eavesdropping, | |||
a client SHOULD send SET_SSV via RPCSEC_GSS with | a client <bcp14>SHOULD</bcp14> send SET_SSV via RPCSEC_GSS with | |||
the privacy service. Several aspects of the SSV | the privacy service. Several aspects of the SSV | |||
make it intractable for an attacker to guess the SSV, | make it intractable for an attacker to guess the SSV, | |||
and thus associate rogue connections with a session, | and thus associate rogue connections with a session, | |||
and rogue sessions with a client ID: | and rogue sessions with a client ID: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The arguments to and results of SET_SSV include digests of the old and | The arguments to and results of SET_SSV include digests of the old and | |||
new SSV, respectively. | new SSV, respectively. | |||
</t> | </li> | |||
<t> | <li> | |||
Because the initial value of the SSV is zero, | Because the initial value of the SSV is zero, | |||
therefore known, the client that opts for SP4_SSV | therefore known, the client that opts for SP4_SSV | |||
protection and opts to apply SP4_SSV protection to | protection and opts to apply SP4_SSV protection to | |||
BIND_CONN_TO_SESSION and CREATE_SESSION MUST send | BIND_CONN_TO_SESSION and CREATE_SESSION <bcp14>MUST</bcp14> send | |||
at least one SET_SSV operation before the first | at least one SET_SSV operation before the first | |||
BIND_CONN_TO_SESSION operation or before the second | BIND_CONN_TO_SESSION operation or before the second | |||
CREATE_SESSION operation on a client ID. If it does | CREATE_SESSION operation on a client ID. If it does | |||
not, the SSV mechanism will not generate tokens | not, the SSV mechanism will not generate tokens | |||
(<xref target="ssv_mech" />). | (<xref target="ssv_mech" format="default"/>). | |||
A client SHOULD send SET_SSV as soon as a session | A client <bcp14>SHOULD</bcp14> send SET_SSV as soon as a session | |||
is created. | is created. | |||
</t> | </li> | |||
<t> | <li> | |||
A SET_SSV request does not replace the SSV with the argument to | A SET_SSV request does not replace the SSV with the argument to | |||
SET_SSV. Instead, the current SSV on the server is logically | SET_SSV. Instead, the current SSV on the server is logically | |||
exclusive ORed (XORed) with the argument to SET_SSV. | exclusive ORed (XORed) with the argument to SET_SSV. | |||
Each time a new principal uses a client ID for the first | Each time a new principal uses a client ID for the first | |||
time, the client | time, the client | |||
SHOULD send a SET_SSV with that principal's RPCSEC_GSS | <bcp14>SHOULD</bcp14> send a SET_SSV with that principal's RPCSEC_GSS | |||
credentials, with RPCSEC_GSS service set to RPC_GSS_SVC_PRIVACY. | credentials, with RPCSEC_GSS service set to RPC_GSS_SVC_PRIVACY. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Here are the types of attacks that can be attempted by an attacker named | Here are the types of attacks that can be attempted by an attacker named | |||
Eve on a victim named Bob, and how SP4_SSV protection foils | Eve on a victim named Bob, and how SP4_SSV protection foils | |||
each attack: | each attack: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
Suppose Eve is the first user to log into a | Suppose Eve is the first user to log into a | |||
legitimate client. Eve's use of an NFSv4.1 | legitimate client. Eve's use of an NFSv4.1 | |||
file system will cause the legitimate client to | file system will cause the legitimate client to | |||
create a client ID | create a client ID | |||
with SP4_SSV protection, specifying that the BIND_CONN_TO_SESSION | with SP4_SSV protection, specifying that the BIND_CONN_TO_SESSION | |||
operation MUST use the SSV credential. Eve's use of | operation <bcp14>MUST</bcp14> use the SSV credential. Eve's use of | |||
the file system also causes an SSV to be created. The | the file system also causes an SSV to be created. The | |||
SET_SSV operation that creates the SSV will be protected by | SET_SSV operation that creates the SSV will be protected by | |||
the RPCSEC_GSS context created by the legitimate | the RPCSEC_GSS context created by the legitimate | |||
client, which uses Eve's GSS principal and | client, which uses Eve's GSS principal and | |||
credentials. Eve can eavesdrop on the network while | credentials. Eve can eavesdrop on the network while | |||
her RPCSEC_GSS context is created and the SET_SSV | her RPCSEC_GSS context is created and the SET_SSV | |||
using her context is sent. Even if the legitimate | using her context is sent. Even if the legitimate | |||
client sends the SET_SSV with RPC_GSS_SVC_PRIVACY, | client sends the SET_SSV with RPC_GSS_SVC_PRIVACY, | |||
because Eve knows her own credentials, she can | because Eve knows her own credentials, she can | |||
decrypt the SSV. Eve can compute an RPCSEC_GSS | decrypt the SSV. Eve can compute an RPCSEC_GSS | |||
credential that BIND_CONN_TO_SESSION will accept, | credential that BIND_CONN_TO_SESSION will accept, | |||
and so associate a new connection with the | and so associate a new connection with the | |||
legitimate session. Eve can change the slot ID and | legitimate session. Eve can change the slot ID and | |||
sequence state of a legitimate session, and/or the | sequence state of a legitimate session, and/or the | |||
SSV state, in such a way that when Bob accesses | SSV state, in such a way that when Bob accesses | |||
the server via the same legitimate client, the | the server via the same legitimate client, the | |||
legitimate client will be unable to use the session. | legitimate client will be unable to use the session. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
The client's only recourse is to create a new client | The client's only recourse is to create a new client | |||
ID for Bob to use, and establish a new SSV for the | ID for Bob to use, and establish a new SSV for the | |||
client ID. The client will be unable to delete | client ID. The client will be unable to delete | |||
the old client ID, and will let the lease on the old | the old client ID, and will let the lease on the old | |||
client ID expire. | client ID expire. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
Once the legitimate client establishes an SSV over | Once the legitimate client establishes an SSV over | |||
the new session using Bob's RPCSEC_GSS context, | the new session using Bob's RPCSEC_GSS context, | |||
Eve can use the new session via the legitimate | Eve can use the new session via the legitimate | |||
client, but she cannot disrupt Bob. Moreover, | client, but she cannot disrupt Bob. Moreover, | |||
because the client SHOULD have modified the SSV | because the client <bcp14>SHOULD</bcp14> have modified the SSV | |||
due to Eve using the new session, Bob cannot get | due to Eve using the new session, Bob cannot get | |||
revenge on Eve by associating a rogue connection | revenge on Eve by associating a rogue connection | |||
with the session. | with the session. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
The question is how did the legitimate client detect | The question is how did the legitimate client detect | |||
that Eve has hijacked the old session? When the | that Eve has hijacked the old session? When the | |||
client detects that a new principal, Bob, wants to | client detects that a new principal, Bob, wants to | |||
use the session, it SHOULD have sent a SET_SSV, | use the session, it <bcp14>SHOULD</bcp14> have sent a SET_SSV, | |||
which leads to the following sub-scenarios: | which leads to the following sub-scenarios: | |||
<vspace blankLines='1' /> | </t> | |||
<ul spacing="normal"> | ||||
<list style="symbols"> | <li> | |||
<t> | <t> | |||
Let us suppose that from the rogue connection, Eve | Let us suppose that from the rogue connection, Eve | |||
sent a SET_SSV with the same slot ID and sequence ID that | sent a SET_SSV with the same slot ID and sequence ID that | |||
the legitimate client later uses. The server will | the legitimate client later uses. The server will | |||
assume the SET_SSV sent with Bob's credentials is a retry, | assume the SET_SSV sent with Bob's credentials is a retry, | |||
and return to the legitimate | and return to the legitimate | |||
client the reply it sent Eve. However, unless Eve can | client the reply it sent Eve. However, unless Eve can | |||
correctly guess the SSV the legitimate client will use, | correctly guess the SSV the legitimate client will use, | |||
the digest verification checks in the SET_SSV response | the digest verification checks in the SET_SSV response | |||
will fail. That is an indication to the client that the | will fail. That is an indication to the client that the | |||
session has apparently been hijacked. | session has apparently been hijacked. | |||
<vspace blankLines='1' /> | </t> | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
Alternatively, Eve sent a SET_SSV with a different slot ID than | Alternatively, Eve sent a SET_SSV with a different slot ID than | |||
the legitimate client uses for its SET_SSV. Then the digest | the legitimate client uses for its SET_SSV. Then the digest | |||
verification of the SET_SSV sent with Bob's credentials fails | verification of the SET_SSV sent with Bob's credentials fails | |||
on the server, and the error returned to the client makes it | on the server, and the error returned to the client makes it | |||
apparent that the session has been hijacked. | apparent that the session has been hijacked. | |||
<vspace blankLines='1' /> | </t> | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
Alternatively, Eve sent an operation other than SET_SSV, | Alternatively, Eve sent an operation other than SET_SSV, | |||
but with the same slot ID and sequence that the legitimate client | but with the same slot ID and sequence that the legitimate client | |||
uses for its SET_SSV. The server returns to the legitimate | uses for its SET_SSV. The server returns to the legitimate | |||
client the response it sent Eve. The client sees that the | client the response it sent Eve. The client sees that the | |||
response is not at all what it expects. The client | response is not at all what it expects. The client | |||
assumes either session hijacking or a server bug, and either way | assumes either session hijacking or a server bug, and either way | |||
destroys the old session. | destroys the old session. | |||
<vspace blankLines='1' /> | </t> | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
Eve associates a rogue connection with the session | Eve associates a rogue connection with the session | |||
as above, and then destroys the session. Again, Bob | as above, and then destroys the session. Again, Bob | |||
goes to use the server from the legitimate client, | goes to use the server from the legitimate client, | |||
which sends a SET_SSV using Bob's credentials. The client receives an err or | which sends a SET_SSV using Bob's credentials. The client receives an err or | |||
that indicates that the session does not exist. When | that indicates that the session does not exist. When | |||
the client tries to create a new session, this | the client tries to create a new session, this | |||
will fail because the SSV it has does not match that which the | will fail because the SSV it has does not match that which the | |||
server has, and now the client knows the session | server has, and now the client knows the session | |||
was hijacked. The legitimate client establishes a | was hijacked. The legitimate client establishes a | |||
new client ID. | new client ID. | |||
<vspace blankLines='1' /> | </t> | |||
</li> | ||||
</t> | <li> | |||
<t> | <t> | |||
If Eve creates a connection before the legitimate | If Eve creates a connection before the legitimate | |||
client establishes an SSV, because the initial | client establishes an SSV, because the initial | |||
value of the SSV is zero and therefore known, | value of the SSV is zero and therefore known, | |||
Eve can send a SET_SSV that will pass the digest | Eve can send a SET_SSV that will pass the digest | |||
verification check. However, because the new | verification check. However, because the new | |||
connection has not been associated with the session, | connection has not been associated with the session, | |||
the SET_SSV is rejected for that reason. | the SET_SSV is rejected for that reason. | |||
<vspace blankLines='1' /> | </t> | |||
</li> | ||||
</t> | </ul> | |||
</list> | <t> | |||
In summary, an attacker's disruption of state when | In summary, an attacker's disruption of state when | |||
SP4_SSV protection is in use is limited to the | SP4_SSV protection is in use is limited to the | |||
formative period of a client ID, its first session, | formative period of a client ID, its first session, | |||
and the establishment of the SSV. Once a non-malicious | and the establishment of the SSV. Once a non-malicious | |||
user uses the client ID, the client quickly detects | user uses the client ID, the client quickly detects | |||
any hijack and rectifies the situation. Once a | any hijack and rectifies the situation. Once a | |||
non-malicious user successfully modifies the SSV, | non-malicious user successfully modifies the SSV, | |||
the attacker cannot use NFSv4.1 operations to disrupt | the attacker cannot use NFSv4.1 operations to disrupt | |||
the non-malicious user. | the non-malicious user. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
Note that neither the SP4_MACH_CRED nor | Note that neither the SP4_MACH_CRED nor | |||
SP4_SSV protection approaches prevent hijacking | SP4_SSV protection approaches prevent hijacking | |||
of a transport connection that has previously been | of a transport connection that has previously been | |||
associated with a session. If the goal of a counter-threat | associated with a session. If the goal of a counter-threat | |||
strategy is to prevent connection hijacking, the use of IPsec is RECOMMENDE | strategy is to prevent connection hijacking, the use of IPsec is <bcp14>REC | |||
D. | OMMENDED</bcp14>. | |||
</t> | </t> | |||
<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 | if EXCHGID4_FLAG_BIND_PRINC_STATEID capability (<xref target="OP_EXCHANGE_I | |||
target="OP_EXCHANGE_ID"/>) is in force, this will | D" 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> <!-- Protection from Unauthorized State Changes --> | </section> | |||
</section> <!-- Sessions Security --> | <section anchor="ssv_mech" numbered="true" toc="default"> | |||
<section title="The Secret State Verifier (SSV) GSS Mechanism" anchor="ssv_mec | <name>The Secret State Verifier (SSV) GSS Mechanism</name> | |||
h"> | <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) | |||
and the SealedMessage token (emitted by GSS_Wrap). | and the SealedMessage token (emitted by GSS_Wrap). | |||
</t> | </t> | |||
<t> | <t> | |||
The mechanism OID for the SSV mechanism is | The mechanism OID for the SSV mechanism is | |||
iso.org.dod.internet.private.enterprise.Michael | iso.org.dod.internet.private.enterprise.Michael | |||
Eisler.nfs.ssv_mech (1.3.6.1.4.1.28882.1.1). While the | Eisler.nfs.ssv_mech (1.3.6.1.4.1.28882.1.1). While the | |||
SSV mechanism does not define any initial context | SSV mechanism does not define any initial context | |||
tokens, the OID can be used to let servers indicate | tokens, the OID can be used to let servers indicate | |||
that the SSV mechanism is acceptable whenever the | that the SSV mechanism is acceptable whenever the | |||
client sends a SECINFO or SECINFO_NO_NAME operation | client sends a SECINFO or SECINFO_NO_NAME operation | |||
(see | (see | |||
<xref target="Security_Service_Negotiation" />). | <xref target="Security_Service_Negotiation" format="default"/>). | |||
</t> | ||||
<t> | </t> | |||
<t> | ||||
The SSV mechanism defines four subkeys derived from | The SSV mechanism defines four subkeys derived from | |||
the SSV value. Each time SET_SSV is invoked, the subkeys | the SSV value. Each time SET_SSV is invoked, the subkeys | |||
are recalculated by the client and server. The | are recalculated by the client and server. The | |||
calculation of each of the four subkeys depends on each | calculation of each of the four subkeys depends on each | |||
of the four respective ssv_subkey4 enumerated values. The calculation | of the four respective ssv_subkey4 enumerated values. The calculation | |||
uses the HMAC | uses the HMAC | |||
<xref target="RFC2104" /> algorithm, using the current SSV as the key, the on e-way hash | <xref target="RFC2104" format="default"/> algorithm, using the current SSV as the key, the one-way hash | |||
algorithm as negotiated by EXCHANGE_ID, | algorithm as negotiated by EXCHANGE_ID, | |||
and the input text as represented by the XDR encoded | and the input text as represented by the XDR encoded | |||
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 MUST 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 | |||
MUST 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 MUST NOT | states that the length of the output of the HMAC algorithm <bcp14>MUST NOT</b | |||
cp14> | ||||
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"/>). | (see <xref target="OP_EXCHANGE_ID" format="default"/>). | |||
</t> | </t> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
/* 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> | ||||
</artwork> | <t> | |||
</figure> | ||||
<t> | ||||
The subkey derived from SSV4_SUBKEY_MIC_I2T | The subkey derived from SSV4_SUBKEY_MIC_I2T | |||
is used for calculating message integrity codes (MICs) | is used for calculating message integrity codes (MICs) | |||
that originate from the NFSv4.1 client, whether as part | that originate from the NFSv4.1 client, whether as part | |||
of a request over the fore channel or a response | of a request over the fore channel or a response | |||
over the backchannel. The subkey derived from | over the backchannel. The subkey derived from | |||
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> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
/* 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> | ||||
</artwork> | <sourcecode type="xdr"><![CDATA[ | |||
</figure> | ||||
<figure> | ||||
<artwork> | ||||
/* 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> | ||||
</artwork> | <t> | |||
</figure> | ||||
<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 | |||
SSV4_SUBKEY_MIC_T2I as the key, the one-way hash algorithm | SSV4_SUBKEY_MIC_T2I as the key, the one-way hash algorithm | |||
as negotiated by EXCHANGE_ID, and the input text | as negotiated by EXCHANGE_ID, and the input text | |||
as represented by data of type ssv_mic_plain_tkn4. | as represented by data of type ssv_mic_plain_tkn4. | |||
The field smpt_ssv_seq is the same as smt_ssv_seq. | The field smpt_ssv_seq is the same as smt_ssv_seq. | |||
The field smpt_orig_plain is the "message" input passed | The field smpt_orig_plain is the "message" input passed | |||
to GSS_GetMIC() (see Section 2.3.1 of <xref target="RFC2743"/>). | to GSS_GetMIC() (see <xref target="RFC2743" sectionFormat="of" section="2.3.1 "/>). | |||
The caller of GSS_GetMIC() provides a pointer to a buffer | The caller of GSS_GetMIC() provides a pointer to a buffer | |||
containing the plain text. The SSV mechanism's entry point for | containing the plain text. The SSV mechanism's entry point for | |||
GSS_GetMIC() encodes this into an opaque array, and the encoding | GSS_GetMIC() encodes this into an opaque array, and the encoding | |||
will include an initial four-byte length, plus any necessary padding. | will include an initial four-byte length, plus any necessary padding. | |||
Prepended to this will be the XDR encoded value of smpt_ssv_seq, | Prepended to this will be the XDR encoded value of smpt_ssv_seq, | |||
thus making up an XDR encoding of a value of data type | thus making up an XDR encoding of a value of data type | |||
ssv_mic_plain_tkn4, which in turn is the input into the HMAC. | ssv_mic_plain_tkn4, which in turn is the input into the HMAC. | |||
</t> | </t> | |||
<t> | <t> | |||
The token emitted by GSS_GetMIC() is XDR encoded and | The token emitted by GSS_GetMIC() is XDR encoded and | |||
of XDR data type ssv_mic_tkn4. The field smt_ssv_seq | of XDR data type ssv_mic_tkn4. The field smt_ssv_seq | |||
comes from the SSV sequence number, which is equal to | comes from the SSV sequence number, which is equal to | |||
one after SET_SSV (<xref target="OP_SET_SSV" />) | one after SET_SSV (<xref target="OP_SET_SSV" format="default"/>) | |||
is called the first time on a client | is called the first time on a client | |||
ID. | ID. | |||
Thereafter, the SSV sequence number is incremented on each SET_SSV. | Thereafter, the SSV sequence number is incremented on each SET_SSV. | |||
Thus, smt_ssv_seq represents the version of the SSV at | Thus, smt_ssv_seq represents the version of the SSV at | |||
the time GSS_GetMIC() was called. As noted in <xref | the time GSS_GetMIC() was called. As noted in <xref target="OP_EXCHANGE_ID" | |||
target="OP_EXCHANGE_ID" />, the client and server | format="default"/>, the client and server | |||
can maintain multiple concurrent versions of the SSV. | can maintain multiple concurrent versions of the SSV. | |||
This allows the SSV to be changed without serializing | This allows the SSV to be changed without serializing | |||
all RPC calls that use the SSV mechanism with SET_SSV | all RPC calls that use the SSV mechanism with SET_SSV | |||
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> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
/* 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> | ||||
</artwork> | <sourcecode type="xdr"><![CDATA[ | |||
</figure> | ||||
<figure> | ||||
<artwork> | ||||
/* 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> | ||||
</artwork> | <t> | |||
</figure> | ||||
<t> | ||||
The token emitted by GSS_Wrap() is XDR encoded and | The token emitted by GSS_Wrap() is XDR encoded and | |||
of XDR data type ssv_seal_cipher_tkn4. | of XDR data type ssv_seal_cipher_tkn4. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
The ssct_ssv_seq field has the same meaning as smt_ssv_seq. | The ssct_ssv_seq field has the same meaning as smt_ssv_seq. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
The ssct_encr_data field is the result of encrypting a | The ssct_encr_data field is the result of encrypting a | |||
value of the XDR encoded data type ssv_seal_plain_tkn4. | value of the XDR encoded data type ssv_seal_plain_tkn4. | |||
The encryption key is the subkey derived from SSV4_SUBKEY_SEAL_I2T | The encryption key is the subkey derived from SSV4_SUBKEY_SEAL_I2T | |||
or SSV4_SUBKEY_SEAL_T2I, and the encryption | or SSV4_SUBKEY_SEAL_T2I, and the encryption | |||
algorithm is that negotiated by EXCHANGE_ID. | algorithm is that negotiated by EXCHANGE_ID. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
The ssct_iv field is the initialization vector (IV) | The ssct_iv field is the initialization vector (IV) | |||
for the encryption algorithm (if applicable) and is | for the encryption algorithm (if applicable) and is | |||
sent in clear text. The content and size of the IV MUST | sent in clear text. The content and size of the IV <bcp14>MUST</bcp14> | |||
comply with the specification of the encryption algorithm. | comply with the specification of the encryption algorithm. | |||
For example, the id-aes256-CBC algorithm MUST use | For example, the id-aes256-CBC algorithm <bcp14>MUST</bcp14> use | |||
a 16-byte initialization vector (IV), which MUST be | a 16-byte initialization vector (IV), which <bcp14>MUST</bcp14> be | |||
unpredictable for each instance of a value of data type | unpredictable for each instance of a value of data type | |||
ssv_seal_plain_tkn4 that is encrypted with a particular | ssv_seal_plain_tkn4 that is encrypted with a particular | |||
SSV key. | SSV key. | |||
</t> | </t> | |||
<t> | <t> | |||
The ssct_hmac field is the result of computing an HMAC using the value | The ssct_hmac field is the result of computing an HMAC using the value | |||
of the XDR encoded data type ssv_seal_plain_tkn4 as the input | of the XDR encoded data type ssv_seal_plain_tkn4 as the input | |||
text. The key is the subkey derived from SSV4_SUBKEY_MIC_I2T or | text. The key is the subkey derived from SSV4_SUBKEY_MIC_I2T or | |||
SSV4_SUBKEY_MIC_T2I, and the one-way hash algorithm is that | SSV4_SUBKEY_MIC_T2I, and the one-way hash algorithm is that | |||
negotiated by EXCHANGE_ID. | negotiated by EXCHANGE_ID. | |||
</t> | </t> | |||
<t> | <t> | |||
The sspt_confounder field is a random value. | The sspt_confounder field is a random value. | |||
</t> | </t> | |||
<t> | <t> | |||
The sspt_ssv_seq field is the same as ssvt_ssv_seq. | The sspt_ssv_seq field is the same as ssvt_ssv_seq. | |||
</t> | </t> | |||
<t> | <t> | |||
The field sspt_orig_plain field is the original plaintext | The field sspt_orig_plain field is the original plaintext | |||
and is the "input_message" input passed to | and is the "input_message" input passed to | |||
GSS_Wrap() (see Section 2.3.3 of <xref target="RFC2743"/>). | GSS_Wrap() (see <xref target="RFC2743" sectionFormat="of" section="2.3.3"/>). | |||
As with the handling of the plaintext by the SSV mechanism's | As with the handling of the plaintext by the SSV mechanism's | |||
GSS_GetMIC() entry point, the entry point for GSS_Wrap() | GSS_GetMIC() entry point, the entry point for GSS_Wrap() | |||
expects a pointer to the plaintext, and will XDR encode | expects a pointer to the plaintext, and will XDR encode | |||
an opaque array into sspt_orig_plain | an opaque array into sspt_orig_plain | |||
representing the plain text, along with | representing the plain text, along with | |||
the other fields of an instance of data type ssv_seal_plain_tkn4. | the other fields of an instance of data type ssv_seal_plain_tkn4. | |||
</t> | </t> | |||
<t> | <t> | |||
The sspt_pad field is present to support encryption | The sspt_pad field is present to support encryption | |||
algorithms that require inputs to be in fixed-sized | algorithms that require inputs to be in fixed-sized | |||
blocks. The content of sspt_pad is zero filled | blocks. The content of sspt_pad is zero filled | |||
except for the length. Beware that the XDR encoding | except for the length. Beware that the XDR encoding | |||
of ssv_seal_plain_tkn4 contains three variable-length | of ssv_seal_plain_tkn4 contains three variable-length | |||
arrays, and so each array consumes four bytes for an | arrays, and so each array consumes four bytes for an | |||
array length, and each array that follows the length | array length, and each array that follows the length | |||
is always padded to a multiple of four bytes per the | is always padded to a multiple of four bytes per the | |||
XDR standard. | XDR standard. | |||
</t> | </t> | |||
<t> | <t> | |||
For example, suppose the encryption algorithm uses 16-byte blocks, and | For example, suppose the encryption algorithm uses 16-byte blocks, and | |||
the sspt_confounder is three bytes long, and | the sspt_confounder is three bytes long, and | |||
the sspt_orig_plain field is 15 bytes long. | the sspt_orig_plain field is 15 bytes long. | |||
The XDR encoding of sspt_confounder uses eight bytes | The XDR encoding of sspt_confounder uses eight bytes | |||
(4 + 3 + 1-byte pad), | (4 + 3 + 1-byte pad), | |||
the XDR encoding of sspt_ssv_seq uses four bytes, | the XDR encoding of sspt_ssv_seq uses four bytes, | |||
the XDR encoding of sspt_orig_plain uses 20 bytes | the XDR encoding of sspt_orig_plain uses 20 bytes | |||
skipping to change at line 4842 ¶ | skipping to change at line 4791 ¶ | |||
and the smallest XDR encoding of the sspt_pad field | and the smallest XDR encoding of the sspt_pad field | |||
is four bytes. | is four bytes. | |||
This totals 36 bytes. The next multiple of 16 is 48; | This totals 36 bytes. The next multiple of 16 is 48; | |||
thus, the length field of sspt_pad needs to be set to | thus, the length field of sspt_pad needs to be set to | |||
12 bytes, or a total encoding of 16 bytes. | 12 bytes, or a total encoding of 16 bytes. | |||
The total number of XDR encoded bytes is thus 8 + | The total number of XDR encoded bytes is thus 8 + | |||
4 + 20 + 16 = 48. | 4 + 20 + 16 = 48. | |||
</t> | </t> | |||
<t> | <t> | |||
GSS_Wrap() emits a token that is an XDR | GSS_Wrap() emits a token that is an XDR | |||
encoding of a value of data type ssv_seal_cipher_tkn4. | encoding of a value of data type ssv_seal_cipher_tkn4. | |||
Note that regardless of whether or not the caller of GSS_Wrap() | Note that regardless of whether or not the caller of GSS_Wrap() | |||
requests confidentiality, the token always has | requests confidentiality, the token always has | |||
confidentiality. This is because the SSV mechanism | confidentiality. This is because the SSV mechanism | |||
is for RPCSEC_GSS, and RPCSEC_GSS never produces | is for RPCSEC_GSS, and RPCSEC_GSS never produces | |||
GSS_wrap() tokens without confidentiality. | GSS_wrap() tokens without confidentiality. | |||
</t> | </t> | |||
<t> | <t> | |||
There is one SSV per client ID. | There is one SSV per client ID. | |||
There is a single GSS context for | There is a single GSS context for | |||
a client ID / SSV pair. | a client ID / SSV pair. | |||
All SSV mechanism RPCSEC_GSS handles of a client ID / SSV pair | All SSV mechanism RPCSEC_GSS handles of a client ID / SSV pair | |||
share the same GSS context. | share the same GSS context. | |||
SSV GSS contexts do not expire except when the SSV | SSV GSS contexts do not expire except when the SSV | |||
is destroyed (causes would include the client ID | is destroyed (causes would include the client ID | |||
being destroyed or a server restart). | being destroyed or a server restart). | |||
Since one | Since one | |||
purpose of context expiration is to replace keys that | purpose of context expiration is to replace keys that | |||
have been in use for "too long", hence vulnerable to | have been in use for "too long", hence vulnerable to | |||
compromise by brute force or accident, the client can | compromise by brute force or accident, the client can | |||
replace the SSV key by | replace the SSV key by | |||
sending periodic SET_SSV operations, which is done by cycling through | sending periodic SET_SSV operations, which is done by cycling through | |||
different users' RPCSEC_GSS credentials. This way, the SSV is | different users' RPCSEC_GSS credentials. This way, the SSV is | |||
replaced without destroying the SSV's GSS contexts. | replaced without destroying the SSV's GSS contexts. | |||
</t> | </t> | |||
<t> | <t> | |||
SSV RPCSEC_GSS handles can be expired or deleted by the server | SSV RPCSEC_GSS handles can be expired or deleted by the server | |||
at any time, and the EXCHANGE_ID operation can be used to create | at any time, and the EXCHANGE_ID operation can be used to create | |||
more SSV RPCSEC_GSS handles. Expiration of SSV RPCSEC_GSS handles | more SSV RPCSEC_GSS handles. Expiration of SSV RPCSEC_GSS handles | |||
does not imply that the SSV or its GSS context has expired. | does not imply that the SSV or its GSS context has expired. | |||
</t> | </t> | |||
<t> | <t> | |||
The client MUST establish an SSV via SET_SSV before the | The client <bcp14>MUST</bcp14> establish an SSV via SET_SSV before the | |||
SSV GSS context can be used to emit tokens from GSS_Wrap() | SSV GSS context can be used to emit tokens from GSS_Wrap() | |||
and GSS_GetMIC(). If SET_SSV has not been successfully | and GSS_GetMIC(). If SET_SSV has not been successfully | |||
called, attempts to emit tokens MUST fail. | called, attempts to emit tokens <bcp14>MUST</bcp14> fail. | |||
</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 | |||
Section 5.2.2, "Context Creation Requests", in <xref target="RFC2203" | "Context Creation Requests", <xref target="RFC2203" sectionFormat="of" sectio | |||
/>). However, <xref target="rpcsec_ssv_consider"/> discusses special | n="5.2.2"/>). However, <xref target="rpcsec_ssv_consider" format="default"/> dis | |||
cusses special | ||||
considerations for the SSV mechanism when used with RPCSEC_GSS. | considerations for the SSV mechanism when used with RPCSEC_GSS. | |||
</t> | </t> | |||
</section> <!-- The SSV GSS Mechanism --> | </section> | |||
<section anchor="rpcsec_ssv_consider" | <section anchor="rpcsec_ssv_consider" numbered="true" toc="default"> | |||
title="Security Considerations for RPCSEC_GSS When Using the SSV Mecha | <name>Security Considerations for RPCSEC_GSS When Using the SSV Mechan | |||
nism"> | ism</name> | |||
<t> | <t> | |||
When a client ID is created with SP4_SSV state protection (see <xref | When a client ID is created with SP4_SSV state protection (see <xref target= | |||
target="OP_EXCHANGE_ID"/>), the client is permitted to associate | "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"/>). Because of the way RPCSEC_GSS | (see <xref target="ssv_mech" format="default"/>). Because of the way RPCSEC_ | |||
(both version 1 and version 2, see <xref target="RFC2203"/> and | GSS | |||
<xref target="RFC5403"/>) calculate the verifier of the reply, | (both version 1 and version 2, see <xref target="RFC2203" format="default"/> | |||
and | ||||
<xref target="RFC5403" format="default"/>) calculate the verifier of the rep | ||||
ly, | ||||
special care must be taken by the implementation of the NFSv4.1 | special care must be taken by the implementation of the NFSv4.1 | |||
client to prevent attacks by a man-in-the-middle. The verifier | client to prevent attacks by a man-in-the-middle. The verifier | |||
of an RPCSEC_GSS reply is the output of GSS_GetMIC() applied to | of an RPCSEC_GSS reply is the output of GSS_GetMIC() applied to | |||
the input value of the seq_num field of the RPCSEC_GSS credential | the input value of the seq_num field of the RPCSEC_GSS credential | |||
(data type rpc_gss_cred_ver_1_t) (see Section 5.3.3.2 of <xref | (data type rpc_gss_cred_ver_1_t) (see <xref target="RFC2203" sectionFormat=" | |||
target="RFC2203"/>). If multiple RPCSEC_GSS handles share the same | of" section="5.3.3.2"/>). If multiple RPCSEC_GSS handles share | |||
the same | ||||
GSS context, then if one handle is used to send a request with the | GSS context, then if one handle is used to send a request with the | |||
same seq_num value as another handle, an attacker could block the | same seq_num value as another handle, an attacker could block the | |||
reply, and replace it with the verifier used for the other handle. | reply, and replace it with the verifier used for the other handle. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
There are multiple ways to prevent the attack on the SSV RPCSEC_GSS | There are multiple ways to prevent the attack on the SSV RPCSEC_GSS | |||
verifier in the reply. The simplest is believed to be as follows. | verifier in the reply. The simplest is believed to be as follows. | |||
<list style='symbols'> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <li> | |||
Each time one or more new SSV RPCSEC_GSS handles are created via | Each time one or more new SSV RPCSEC_GSS handles are created via | |||
EXCHANGE_ID, the client SHOULD send a SET_SSV operation to modify | EXCHANGE_ID, the client <bcp14>SHOULD</bcp14> send a SET_SSV operation to mod ify | |||
the SSV. By changing the SSV, the new handles will not result in the | the SSV. By changing the SSV, the new handles will not result in the | |||
re-use of an SSV RPCSEC_GSS verifier in a reply. | re-use of an SSV RPCSEC_GSS verifier in a reply. | |||
</t> | </li> | |||
<li> | ||||
<t> | When a requester decides to use N SSV RPCSEC_GSS handles, it <bcp14>SHOULD</b | |||
When a requester decides to use N SSV RPCSEC_GSS handles, it SHOULD | cp14> | |||
assign a unique and non-overlapping range of seq_nums to each SSV | assign a unique and non-overlapping range of seq_nums to each SSV | |||
RPCSEC_GSS handle. The size of each range SHOULD be equal to MAXSEQ | RPCSEC_GSS handle. The size of each range <bcp14>SHOULD</bcp14> be equal to M | |||
/ N (see Section 5 of <xref target="RFC2203"/> for the definition | AXSEQ | |||
/ N (see <xref target="RFC2203" sectionFormat="of" section="5"/> for the defi | ||||
nition | ||||
of MAXSEQ). When an SSV RPCSEC_GSS handle reaches its maximum, it | of MAXSEQ). When an SSV RPCSEC_GSS handle reaches its maximum, it | |||
SHOULD force the replier to destroy the handle by sending a NULL | <bcp14>SHOULD</bcp14> force the replier to destroy the handle by sending a NU | |||
RPC request with seq_num set to MAXSEQ + 1 (see Section 5.3.3.3 of | LL | |||
<xref target="RFC2203"/>). | RPC request with seq_num set to MAXSEQ + 1 (see | |||
<xref target="RFC2203" sectionFormat="of" section="5.3.3.3"/>). | ||||
</t> | ||||
<t> | </li> | |||
When the requester wants to increase or decrease N, it SHOULD force | <li> | |||
When the requester wants to increase or decrease N, it <bcp14>SHOULD</bcp14> | ||||
force | ||||
the replier to destroy all N handles by sending a NULL RPC request on | the replier to destroy all N handles by sending a NULL RPC request on | |||
each handle with seq_num set to MAXSEQ + 1. If the requester is the | each handle with seq_num set to MAXSEQ + 1. If the requester is the | |||
client, it SHOULD send a SET_SSV operation before using new handles. | client, it <bcp14>SHOULD</bcp14> send a SET_SSV operation before using new ha | |||
If the requester is the server, then the client SHOULD send a SET_SSV | ndles. | |||
If the requester is the server, then the client <bcp14>SHOULD</bcp14> send a | ||||
SET_SSV | ||||
operation when it detects that the server has forced it to destroy a | operation when it detects that the server has forced it to destroy a | |||
backchannel's SSV RPCSEC_GSS handle. By sending a SET_SSV operation, | backchannel's SSV RPCSEC_GSS handle. By sending a SET_SSV operation, | |||
the SSV will change, and so the attacker will be unavailable to | the SSV will change, and so the attacker will be unavailable to | |||
successfully replay a previous verifier in a reply to the requester. | successfully replay a previous verifier in a reply to the requester. | |||
</t> | </li> | |||
</ul> | ||||
</list> | <t> | |||
</t> | ||||
<t> | ||||
Note that if the replier carefully creates the SSV RPCSEC_GSS | Note that if the replier carefully creates the SSV RPCSEC_GSS | |||
handles, the related risk of a man-in-the-middle splicing a forged | handles, the related risk of a man-in-the-middle splicing a forged | |||
SSV RPCSEC_GSS credential with a verifier for another handle does | SSV RPCSEC_GSS credential with a verifier for another handle does | |||
not exist. This is because the verifier in an RPCSEC_GSS request | not exist. This is because the verifier in an RPCSEC_GSS request | |||
is computed from input that includes both the RPCSEC_GSS handle and | is computed from input that includes both the RPCSEC_GSS handle and | |||
seq_num (see Section 5.3.1 of <xref target="RFC2203"/>). Provided the | seq_num (see <xref target="RFC2203" sectionFormat="of" section="5.3.1"/>). P rovided the | |||
replier takes care to avoid re-using the value of an RPCSEC_GSS | replier takes care to avoid re-using the value of an RPCSEC_GSS | |||
handle that it creates, such as by including a generation number in the | handle that it creates, such as by including a generation number in the | |||
handle, the man-in-the-middle will not be able to successfully replay | handle, the man-in-the-middle will not be able to successfully replay | |||
a previous verifier in the request to a replier. | a previous verifier in the request to a replier. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section anchor="Session_Mechanics_Steady_State" numbered="true" toc="de | |||
fault"> | ||||
<section anchor="Session_Mechanics_Steady_State" title="Session Mechanics - St | <name>Session Mechanics - Steady State</name> | |||
eady State"> | <section anchor="Obligations_of_the_Server" numbered="true" toc="defau | |||
lt"> | ||||
<section anchor="Obligations_of_the_Server" title="Obligations of the Server" | <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_Ac | server takes action as specified in <xref target="Events_Requiring_Server_Ac | |||
tion" />. | tion" format="default"/>. | |||
</t> | </t> | |||
</section> <!-- Obligations of the Server --> | </section> | |||
<section anchor="Obligations_of_the_Client" title="Obligations of the Client" | <section anchor="Obligations_of_the_Client" numbered="true" toc="default"> | |||
> | <name>Obligations of the Client</name> | |||
<t> | <t> | |||
The client SHOULD 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: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<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 | |||
that requires a session but nonetheless is not | that requires a session but nonetheless is not | |||
sending operations risks having the session be destroyed | sending operations risks having the session be destroyed | |||
by the server. This is because sessions consume | by the server. This is because sessions consume | |||
resources, and resource limitations may force the | resources, and resource limitations may force the | |||
server to cull an inactive session. A server MAY consider | server to cull an inactive session. A server <bcp14>MAY</bcp14> consider | |||
a session to be inactive if the client has not used | a session to be inactive if the client has not used | |||
the session before the session inactivity timer (<xref | the session before the session inactivity timer (<xref target="session_inac | |||
target="session_inactive"/>) has expired. | tive" format="default"/>) has expired. | |||
</t> | </li> | |||
<t> | <li> | |||
Destroy the session when not needed. If a client has | Destroy the session when not needed. If a client has | |||
multiple sessions, one of which has no | multiple sessions, one of which has no | |||
requests waiting for replies, and has been idle for | requests waiting for replies, and has been idle for | |||
some period of time, it SHOULD destroy the session. | some period of time, it <bcp14>SHOULD</bcp14> destroy the session. | |||
</t> | </li> | |||
<t> | <li> | |||
Maintain GSS contexts and RPCSEC_GSS handles | Maintain GSS contexts and RPCSEC_GSS handles | |||
for the backchannel. If the client | for the backchannel. If the client | |||
requires the server to use the RPCSEC_GSS security | requires the server to use the RPCSEC_GSS security | |||
flavor for callbacks, then it needs to be sure the | flavor for callbacks, then it needs to be sure the | |||
RPCSEC_GSS handles and/or their GSS | RPCSEC_GSS handles and/or their GSS | |||
contexts that are handed to the server via BACKCHANNEL_CTL or | contexts that are handed to the server via BACKCHANNEL_CTL or | |||
CREATE_SESSION are unexpired. | CREATE_SESSION are unexpired. | |||
</t> | </li> | |||
<t> | <li> | |||
Preserve a connection for a backchannel. The server | Preserve a connection for a backchannel. The server | |||
requires a backchannel in order to gracefully recall | requires a backchannel in order to gracefully recall | |||
recallable state or notify the client of certain | recallable state or notify the client of certain | |||
events. Note that if the connection is not being used | events. Note that if the connection is not being used | |||
for the fore channel, there is no way for the client to tell | for the fore channel, there is no way for the client to tell | |||
if the connection is still alive (e.g., the server | if the connection is still alive (e.g., the server | |||
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. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> <!-- Obligations of the Client --> | ||||
<section anchor="Steps_the_Client_Takes_To_Establish_a_Session" | <section anchor="Steps_the_Client_Takes_To_Establish_a_Session" numbered="tru | |||
title="Steps the Client Takes to Establish a Session"> | e" toc="default"> | |||
<t> | <name>Steps the Client Takes to Establish a Session</name> | |||
<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 SHOULD 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. | |||
If it opts for SP4_SSV protection, the client needs to | If it opts for SP4_SSV protection, the client needs to | |||
ask for SSV-based RPCSEC_GSS handles. | ask for SSV-based RPCSEC_GSS handles. | |||
</t> | </t> | |||
<t> | <t> | |||
The client uses the client ID to send a | The client uses the client ID to send a | |||
CREATE_SESSION on a connection to the server. | CREATE_SESSION on a connection to the server. | |||
The results of CREATE_SESSION indicate whether or not the | The results of CREATE_SESSION indicate whether or not the | |||
server will persist the session reply cache through | server will persist the session reply cache through | |||
a server that has restarted, and the client notes this | a server that has restarted, and the client notes this | |||
for future reference. | for future reference. | |||
</t> | </t> | |||
<t> | <t> | |||
If the client specified SP4_SSV state protection | If the client specified SP4_SSV state protection | |||
when the client ID was created, then it SHOULD send | when the client ID was created, then it <bcp14>SHOULD</bcp14> send | |||
SET_SSV in the first COMPOUND after the session is | SET_SSV in the first COMPOUND after the session is | |||
created. Each time a new principal goes to use the | created. Each time a new principal goes to use the | |||
client ID, it SHOULD send a SET_SSV again. | client ID, it <bcp14>SHOULD</bcp14> send a SET_SSV again. | |||
</t> | </t> | |||
<t> | <t> | |||
If the client wants to use delegations, layouts, | If the client wants to use delegations, layouts, | |||
directory notifications, or any other state that | directory notifications, or any other state that | |||
requires a backchannel, then it needs to add a connection | requires a backchannel, then it needs to add a connection | |||
to the backchannel if CREATE_SESSION did not already | to the backchannel if CREATE_SESSION did not already | |||
do so. The client creates a connection, and calls | do so. The client creates a connection, and calls | |||
BIND_CONN_TO_SESSION to associate the connection | BIND_CONN_TO_SESSION to associate the connection | |||
with the session and the session's backchannel. If | with the session and the session's backchannel. If | |||
CREATE_SESSION did not already do so, the client MUST | CREATE_SESSION did not already do so, the client <bcp14>MUST</bcp14> | |||
tell the server what security is required in order | tell the server what security is required in order | |||
for the client to accept callbacks. The client does | for the client to accept callbacks. The client does | |||
this via BACKCHANNEL_CTL. If the client selected | this via BACKCHANNEL_CTL. If the client selected | |||
SP4_MACH_CRED or SP4_SSV protection when it called | SP4_MACH_CRED or SP4_SSV protection when it called | |||
EXCHANGE_ID, then the client SHOULD specify that the | EXCHANGE_ID, then the client <bcp14>SHOULD</bcp14> specify that the | |||
backchannel use RPCSEC_GSS contexts for security. | backchannel use RPCSEC_GSS contexts for security. | |||
</t> | </t> | |||
<t> | <t> | |||
If the client wants to use additional | If the client wants to use additional | |||
connections for the backchannel, then it needs to call | connections for the backchannel, then it needs to call | |||
BIND_CONN_TO_SESSION on each connection it wants to | BIND_CONN_TO_SESSION on each connection it wants to | |||
use with the session. If the client wants to use | use with the session. If the client wants to use | |||
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> <!-- Steps the Client Takes To Establish a Session --> | </section> | |||
</section> <!-- Session Mechanics - Steady State --> | </section> | |||
<section anchor="session_inactive" title="Session Inactivity Timer" > | <section anchor="session_inactive" numbered="true" toc="default"> | |||
<t> | <name>Session Inactivity Timer</name> | |||
The server MAY maintain a session inactivity timer for | <t> | |||
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 MAY 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 MUST 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 MUST NOT be less than the lease_time | inactivity timer <bcp14>MUST NOT</bcp14> be less than the lease_time | |||
attribute (<xref target="attrdef_lease_time"/>). | attribute (<xref target="attrdef_lease_time" format="default"/>). | |||
As with lease renewal (<xref target="lease_renewal"/>), | As with lease renewal (<xref target="lease_renewal" format="default"/>), | |||
when the server receives a SEQUENCE operation, | when the server receives a SEQUENCE operation, | |||
it resets the session inactivity timer, and MUST NOT allow the | it resets the session inactivity timer, and <bcp14>MUST NOT</bcp14> allow the | |||
timer to expire while the rest of the operations in the | timer to expire while the rest of the operations in the | |||
COMPOUND procedure's request are still executing. Once the | COMPOUND procedure's request are still executing. Once the | |||
last operation has finished, the server MUST set the session | last operation has finished, the server <bcp14>MUST</bcp14> set the session | |||
inactivity timer to expire no sooner than the sum of the | inactivity timer to expire no sooner than the sum of the | |||
current time and the value of the lease_time attribute. | current time and the value of the lease_time attribute. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section anchor="Session_Mechanics_Recovery" numbered="true" toc="defaul | |||
<section anchor="Session_Mechanics_Recovery" title="Session Mechanics - Recove | t"> | |||
ry"> | <name>Session Mechanics - Recovery</name> | |||
<section anchor="Events_Requiring_Client_Action" numbered="true" toc=" | ||||
<section anchor="Events_Requiring_Client_Action" title="Events Requiring Clie | default"> | |||
nt Action"> | <name>Events Requiring Client Action</name> | |||
<t> | ||||
<t> | ||||
The following events require client action to recover. | The following events require client action to recover. | |||
</t> | </t> | |||
<section title="RPCSEC_GSS Context Loss by Callback Path"> | <section numbered="true" toc="default"> | |||
<t> | <name>RPCSEC_GSS Context Loss by Callback Path</name> | |||
<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 MUST | 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 handle s | sr_status_flags field of the SEQUENCE results indicates when callback handle s | |||
are nearly expired, or fully expired (see <xref target="OP_SEQUENCE_DESCRIPT | are nearly expired, or fully expired (see <xref target="OP_SEQUENCE_DESCRIPT | |||
ION"/>). | ION" format="default"/>). | |||
</t> | </t> | |||
</section> <!-- RPCSEC_GSS Context Loss by Callback_Path --> | </section> | |||
<section title="Connection Loss"> | <section numbered="true" toc="default"> | |||
<t> | <name>Connection Loss</name> | |||
<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 MUST 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. | |||
</t> | </t> | |||
<t> | <t> | |||
If there was a request outstanding at the time | If there was a request outstanding at the time | |||
of connection loss, then if the client wants to continue | of connection loss, then if the client wants to continue | |||
to use the session, it MUST retry the request, as | to use the session, it <bcp14>MUST</bcp14> retry the request, as | |||
described in | described in | |||
<xref target="Retry_and_Replay" />. 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 | with the same source network address or the same | |||
destination network address as the lost connection. As | destination network address as the lost connection. As | |||
long as the session ID, slot ID, and sequence ID in the | long as the session ID, slot ID, and sequence ID in the | |||
retry match that of the original request, the server | retry match that of the original request, the server | |||
will recognize the request as a retry if it executed | will recognize the request as a retry if it executed | |||
the request prior to disconnect. | the request prior to disconnect. | |||
</t> | </t> | |||
<t> | <t> | |||
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 | |||
MUST 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 SHOULD 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> <!-- Connection Disconnect --> | </section> | |||
<section title="Backchannel GSS Context Loss"> | <section numbered="true" toc="default"> | |||
<t> | <name>Backchannel GSS Context Loss</name> | |||
<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> <!-- Backchannel GSS Context Loss --> | </section> | |||
<section anchor="loss_of_session" title="Loss of Session"> | <section anchor="loss_of_session" numbered="true" toc="default"> | |||
<t> | <name>Loss of Session</name> | |||
<t> | ||||
The replier might lose a record of the session. Causes include: | The replier might lose a record of the session. Causes include: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Replier failure and restart. | Replier failure and restart. | |||
</t> | </li> | |||
<t> | <li> | |||
A catastrophe that causes the reply cache to be corrupted or | A catastrophe that causes the reply cache to be corrupted or | |||
lost on the media on which it was stored. This applies | lost on the media on which it was stored. This applies | |||
even if the replier indicated in the CREATE_SESSION results | even if the replier indicated in the CREATE_SESSION results | |||
that it would persist the cache. | that it would persist the cache. | |||
</t> | </li> | |||
<t> | <li> | |||
The server purges the session of a client that has been | The server purges the session of a client that has been | |||
inactive for a very extended period of time. | inactive for a very extended period of time. | |||
</t> | </li> | |||
<t> | <li> | |||
As a result of configuration changes among a set of clustered | As a result of configuration changes among a set of clustered | |||
servers, a network address previously connected to one | servers, a network address previously connected to one | |||
server becomes connected to a different server that has | server becomes connected to a different server that has | |||
no knowledge of the session in question. Such a configuration | no knowledge of the session in question. Such a configuration | |||
change will generally only happen when the original server | change will generally only happen when the original server | |||
ceases to function for a time. | ceases to function for a time. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
Loss of reply cache is equivalent to loss of session. | Loss of reply cache is equivalent to loss of session. | |||
The replier indicates loss of session to the requester | The replier indicates loss of session to the requester | |||
by returning NFS4ERR_BADSESSION on the next operation | by returning NFS4ERR_BADSESSION on the next operation | |||
that uses the session ID that refers to the lost | that uses the session ID that refers to the lost | |||
session. | session. | |||
</t> | </t> | |||
<t> | <t> | |||
After an event like a server restart, the client may have | After an event like a server restart, the client may have | |||
lost its connections. The client assumes for the moment | lost its connections. The client assumes for the moment | |||
that the session has not been lost. It reconnects, and | that the session has not been lost. It reconnects, and | |||
if it specified connection association enforcement when | if it specified connection association enforcement when | |||
the session was created, it | the session was created, it | |||
invokes BIND_CONN_TO_SESSION using the session ID. Otherwise, | invokes BIND_CONN_TO_SESSION using the session ID. Otherwise, | |||
it invokes SEQUENCE. If | it invokes SEQUENCE. If | |||
BIND_CONN_TO_SESSION or SEQUENCE returns NFS4ERR_BADSESSION, the | BIND_CONN_TO_SESSION or SEQUENCE returns NFS4ERR_BADSESSION, the | |||
client knows the session is not available to it when communicating | client knows the session is not available to it when communicating | |||
with that network address. If the connection survives | with that network address. If the connection survives | |||
session loss, then the next SEQUENCE operation the client | session loss, then the next SEQUENCE operation the client | |||
sends over the connection will get back NFS4ERR_BADSESSION. | sends over the connection will get back NFS4ERR_BADSESSION. | |||
The client again knows the session was lost. | The client again knows the session was lost. | |||
</t> | </t> | |||
<t> | <t> | |||
Here is one suggested algorithm for the client when it gets | Here is one suggested algorithm for the client when it gets | |||
NFS4ERR_BADSESSION. It is not obligatory in that, if a | NFS4ERR_BADSESSION. It is not obligatory in that, if a | |||
client does not want to take advantage of such features as | client does not want to take advantage of such features as | |||
trunking, it may omit parts of it. However, it is a useful | trunking, it may omit parts of it. However, it is a useful | |||
example that draws attention to various possible recovery | example that draws attention to various possible recovery | |||
issues: | issues: | |||
<list style="numbers"> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<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. | |||
</t> | </li> | |||
<t> | <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. | |||
</t> | </li> | |||
<t> | <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 | |||
associated with that session ID. It is possible the | associated with that session ID. It is possible the | |||
session is still alive and available on other | session is still alive and available on other | |||
network addresses. The client sends an EXCHANGE_ID | network addresses. The client sends an EXCHANGE_ID | |||
on all the connections to see if the server owner | on all the connections to see if the server owner | |||
is still listening on those network addresses. | is still listening on those network addresses. | |||
If the same server owner is returned but a new | If the same server owner is returned but a new | |||
client ID is returned, this is a strong | client ID is returned, this is a strong | |||
skipping to change at line 5290 ¶ | skipping to change at line 5236 ¶ | |||
has no other sessions for that client ID. | has no other sessions for that client ID. | |||
If a different server owner is returned, | If a different server owner is returned, | |||
the client can use DNS to find | the client can use DNS to find | |||
other network addresses. If it does not, or if | other network addresses. If it does not, or if | |||
DNS does not find any other addresses for the server, | DNS does not find any other addresses for the server, | |||
then the client will be unable to provide NFSv4.1 | then the client will be unable to provide NFSv4.1 | |||
service, and fatal errors should be returned | service, and fatal errors should be returned | |||
to processes that were using the server. If the | to processes that were using the server. If the | |||
client is using a "mount" paradigm, unmounting | client is using a "mount" paradigm, unmounting | |||
the server is advised. | the server is advised. | |||
</t> | </li> | |||
<t> | <li> | |||
If the client knows of no other connections associated | If the client knows of no other connections associated | |||
with the session ID and server network addresses that | with the session ID and server network addresses that | |||
are, or have been, associated with the session ID, | are, or have been, associated with the session ID, | |||
then the client can use DNS to find | then the client can use DNS to find | |||
other network addresses. If it does not, or if | other network addresses. If it does not, or if | |||
DNS does not find any other addresses for the server, | DNS does not find any other addresses for the server, | |||
then the client will be unable to provide NFSv4.1 | then the client will be unable to provide NFSv4.1 | |||
service, and fatal errors should be returned | service, and fatal errors should be returned | |||
to processes that were using the server. If the | to processes that were using the server. If the | |||
client is using a "mount" paradigm, unmounting | client is using a "mount" paradigm, unmounting | |||
the server is advised. | the server is advised. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | <t> | |||
<t> | ||||
If there is a reconfiguration event that results in the | If there is a reconfiguration event that results in the | |||
same network address being assigned to servers where the | same network address being assigned to servers where the | |||
eir_server_scope value is different, it cannot be guaranteed | eir_server_scope value is different, it cannot be guaranteed | |||
that a session ID generated by the first will be recognized | that a session ID generated by the first will be recognized | |||
as invalid by the first. Therefore, in managing server | as invalid by the first. Therefore, in managing server | |||
reconfigurations among servers with different server scope | reconfigurations among servers with different server scope | |||
values, it is necessary to make sure that all clients have | values, it is necessary to make sure that all clients have | |||
disconnected from the first server before effecting | disconnected from the first server before effecting | |||
the reconfiguration. Nonetheless, clients should not | the reconfiguration. Nonetheless, clients should not | |||
assume that servers will always adhere to this requirement; | assume that servers will always adhere to this requirement; | |||
clients MUST be prepared to deal with unexpected | clients <bcp14>MUST</bcp14> be prepared to deal with unexpected | |||
effects of server reconfigurations. | effects of server reconfigurations. | |||
Even where a session ID is inappropriately | Even where a session ID is inappropriately | |||
recognized as valid, it is likely either that the connection | recognized as valid, it is likely either that the connection | |||
will not be recognized as valid or that a sequence value | will not be recognized as valid or that a sequence value | |||
for a slot will not be correct. Therefore, when a client | for a slot will not be correct. Therefore, when a client | |||
receives results indicating such unexpected errors, the use of | receives results indicating such unexpected errors, the use of | |||
EXCHANGE_ID to determine the current server configuration | EXCHANGE_ID to determine the current server configuration | |||
is RECOMMENDED. | is <bcp14>RECOMMENDED</bcp14>. | |||
</t> | </t> | |||
<t> | <t> | |||
A variation on the above is that after a server's network | A variation on the above is that after a server's network | |||
address moves, there is no NFSv4.1 server listening, e.g., no | address moves, there is no NFSv4.1 server listening, e.g., no | |||
listener on port 2049. In this example, one of the following occur: the NF Sv4 server returns | listener on port 2049. In this example, one of the following occur: the NF Sv4 server returns | |||
NFS4ERR_MINOR_VERS_MISMATCH, the NFS server returns a | NFS4ERR_MINOR_VERS_MISMATCH, the NFS server returns a | |||
PROG_MISMATCH error, the RPC listener on 2049 returns | PROG_MISMATCH error, the RPC listener on 2049 returns | |||
PROG_UNVAIL, or attempts to reconnect to the network address | PROG_UNVAIL, or attempts to reconnect to the network address | |||
timeout. These SHOULD be treated as equivalent to SEQUENCE | timeout. These <bcp14>SHOULD</bcp14> be treated as equivalent to SEQUENCE | |||
returning NFS4ERR_BADSESSION for these purposes. | returning NFS4ERR_BADSESSION for these purposes. | |||
</t> | </t> | |||
<t> | <t> | |||
When the client detects session loss, it needs to call CREATE_SESSION | When the client detects session loss, it needs to call CREATE_SESSION | |||
to recover. Any non-idempotent operations that were in progress | to recover. Any non-idempotent operations that were in progress | |||
might have been performed on the server at the time of | might have been performed on the server at the time of | |||
session loss. The client has no general way to recover from this. | session loss. The client has no general way to recover from this. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that loss of session does not imply loss of byte-range lock, open, del egation, | Note that loss of session does not imply loss of byte-range lock, open, del egation, | |||
or layout state because locks, opens, delegations, and layouts | or layout state because locks, opens, delegations, and layouts | |||
are tied to the client ID and depend on the client ID, not the session. | are tied to the client ID and depend on the client ID, not the session. | |||
Nor does loss of byte-range lock, open, delegation, | Nor does loss of byte-range lock, open, delegation, | |||
or layout state imply loss of session state, because the session depends | or layout state imply loss of session state, because the session depends | |||
on the client ID; loss of client ID however does imply loss of | on the client ID; loss of client ID however does imply loss of | |||
session, byte-range lock, open, delegation, and layout state. | session, byte-range lock, open, delegation, and layout state. | |||
See <xref target="server_failure" />. | See <xref target="server_failure" format="default"/>. | |||
A session can survive a server restart, | A session can survive a server restart, | |||
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> <!-- Loss of Session --> | </section> | |||
</section> <!-- Events Requiring Client Action --> | </section> | |||
<section anchor="Events_Requiring_Server_Action" title="Events Requiring Serv | <section anchor="Events_Requiring_Server_Action" numbered="true" toc="default | |||
er Action"> | "> | |||
<t> | <name>Events Requiring Server Action</name> | |||
<t> | ||||
The following events require server action to recover. | The following events require server action to recover. | |||
</t> | </t> | |||
<section title="Client Crash and Restart"> | <section numbered="true" toc="default"> | |||
<t> | <name>Client Crash and Restart</name> | |||
As described in <xref target="OP_EXCHANGE_ID" />, | <t> | |||
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> <!-- Client Crash and Restart --> | </section> | |||
<section title="Client Crash with No Restart" anchor="client_crash_no_restar | <section anchor="client_crash_no_restart" numbered="true" toc="default"> | |||
t"> | <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 MAY destroy the old | and if the server has resource constraints, it <bcp14>MAY</bcp14> destroy th e old | |||
session as well as locking state. | session as well as locking state. | |||
</t> | </t> | |||
</section> <!-- Client Crash with No Restart --> | </section> | |||
<section title="Extended Network Partition"> | <section numbered="true" toc="default"> | |||
<t> | <name>Extended Network Partition</name> | |||
<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" />). | <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> <!-- "Extended Network Partition" --> | </section> | |||
<section title="Backchannel Connection Loss"> | <section numbered="true" toc="default"> | |||
<t> | <name>Backchannel Connection Loss</name> | |||
<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 | |||
MUST retry the requests, as described in | <bcp14>MUST</bcp14> retry the requests, as described in | |||
<xref target="Retry_and_Replay" />. 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 | |||
the session ID, slot ID, and sequence ID in the retry | the session ID, slot ID, and sequence ID in the retry | |||
match that of the original request, the callback target will | match that of the original request, the callback target will | |||
recognize the request as a retry even if it did see the request | recognize the request as a retry even if it did see the request | |||
prior to disconnect. | prior to disconnect. | |||
</t> | </t> | |||
<t> | <t> | |||
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 MUST indicate that in the sr_status_flags field of | then the server <bcp14>MUST</bcp14> indicate that in the sr_status_flags fi eld 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" /> 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> <!-- Backchannel Connection Loss --> | </section> | |||
<section title="GSS Context Loss"> | <section numbered="true" toc="default"> | |||
<t> | <name>GSS Context Loss</name> | |||
The server SHOULD monitor when the number of RPCSEC_GSS | <t> | |||
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 MUST 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> <!-- GSS Context Loss --> | </section> | |||
</section> <!-- Events Requiring Server Action --> | </section> | |||
</section> <!-- Session Mechanics - Recovery --> | </section> | |||
<section title="Parallel NFS and Sessions" anchor="pnfs_and_sessions"> | <section anchor="pnfs_and_sessions" numbered="true" toc="default"> | |||
<t> | <name>Parallel NFS and Sessions</name> | |||
<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 crea ted | and results to allow the client to indicate how it wants to use sessions crea ted | |||
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" /> for pNFS sessions considerations. | See <xref target="pnfs_session_stuff" format="default"/> for pNFS sessions co | |||
</t> | nsiderations. | |||
</section> <!-- Parallel NFS and Sessions --> | </t> | |||
</section> <!-- Session --> | </section> | |||
</section> <!-- Core Infrastructure --> | </section> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | </section> | |||
$ --> | <section numbered="true" toc="default"> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <name>Protocol Constants and Data Types</name> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <t> | |||
<section title="Protocol Constants and Data Types"> | ||||
<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">RFC 4506</xref> and R | protocol are defined in the XDR (<xref target="RFC4506" format="default">RFC | |||
PC | 4506</xref>) and RPC | |||
<xref target="RFC5531">RFC 5531</xref> documents. The next sections | (<xref target="RFC5531" format="default">RFC 5531</xref>) documents. The ne | |||
xt 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 targe | specific to this protocol. The full list of XDR data types is in <xref targe | |||
t="RFC5662" />. | t="RFC5662" format="default"/>. | |||
</t> | </t> | |||
<section numbered="true" toc="default"> | ||||
<section title="Basic Constants"> | <name>Basic Constants</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
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; | |||
const NFS4_MAXFILELEN = 0xffffffffffffffff; | const NFS4_MAXFILELEN = 0xffffffffffffffff; | |||
const NFS4_MAXFILEOFF = 0xfffffffffffffffe; | const NFS4_MAXFILEOFF = 0xfffffffffffffffe; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
<t> | ||||
Except where noted, all these constants are defined in bytes. | Except where noted, all these constants are defined in bytes. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
NFS4_FHSIZE is the maximum size of a filehandle. | NFS4_FHSIZE is the maximum size of a filehandle. | |||
</t> | </li> | |||
<t> | <li> | |||
NFS4_VERIFIER_SIZE is the fixed size of a verifier. | NFS4_VERIFIER_SIZE is the fixed size of a verifier. | |||
</t> | </li> | |||
<t> | <li> | |||
NFS4_OPAQUE_LIMIT is the maximum size of certain | NFS4_OPAQUE_LIMIT is the maximum size of certain | |||
opaque information. | opaque information. | |||
</t> | </li> | |||
<t> | <li> | |||
NFS4_SESSIONID_SIZE is the fixed size of a session identifier. | NFS4_SESSIONID_SIZE is the fixed size of a session identifier. | |||
</t> | </li> | |||
<t> | <li> | |||
NFS4_INT64_MAX is the maximum value of a signed 64-bit integer. | NFS4_INT64_MAX is the maximum value of a signed 64-bit integer. | |||
</t> | </li> | |||
<t> | <li> | |||
NFS4_UINT64_MAX is the maximum value of an unsigned 64-bit integer. | NFS4_UINT64_MAX is the maximum value of an unsigned 64-bit integer. | |||
</t> | </li> | |||
<t> | <li> | |||
NFS4_INT32_MAX is the maximum value of a signed 32-bit integer. | NFS4_INT32_MAX is the maximum value of a signed 32-bit integer. | |||
</t> | </li> | |||
<t> | <li> | |||
NFS4_UINT32_MAX is the maximum value of an unsigned 32-bit integer. | NFS4_UINT32_MAX is the maximum value of an unsigned 32-bit integer. | |||
</t> | </li> | |||
<t> | <li> | |||
NFS4_MAXFILELEN is the maximum length of a regular file. | NFS4_MAXFILELEN is the maximum length of a regular file. | |||
</t> | </li> | |||
<t> | <li> | |||
NFS4_MAXFILEOFF is the maximum offset into a regular file. | NFS4_MAXFILEOFF is the maximum offset into a regular file. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section numbered="true" toc="default"> | |||
<name>Basic Data Types</name> | ||||
<section title="Basic Data Types"> | <t> | |||
<t> | ||||
These are the base NFSv4.1 data types. | These are the base NFSv4.1 data types. | |||
</t> | </t> | |||
<texttable anchor='basic_data_types'> | <table anchor="basic_data_types" align="center"> | |||
<thead> | ||||
<ttcol align='left'>Data Type</ttcol> | <tr> | |||
<ttcol align='left'>Definition</ttcol> | <th align="left">Data Type</th> | |||
<c>int32_t</c> <c>typedef int int32_t;</c> | <th align="left">Definition</th> | |||
</tr> | ||||
<c>uint32_t</c> <c>typedef unsigned int uint32_t;</c> | </thead> | |||
<tbody> | ||||
<c>int64_t</c> <c>typedef hyper int64_t;</c> | <tr> | |||
<td align="left">int32_t</td> | ||||
<c>uint64_t</c> <c>typedef unsigned hyper uint64_t;</c> | <td align="left">typedef int int32_t;</td> | |||
</tr> | ||||
<c>attrlist4</c> <c>typedef opaque attrlist4<>;</c> | <tr> | |||
<c/> <c>Used for file/directory attributes.</c> | <td align="left">uint32_t</td> | |||
<td align="left">typedef unsigned int uint32_t;</td> | ||||
<c>bitmap4</c> <c>typedef uint32_t bitmap4<>;</c> | </tr> | |||
<c/> <c>Used in attribute array encoding.</c> | <tr> | |||
<td align="left">int64_t</td> | ||||
<c>changeid4</c> <c>typedef uint64_t changeid4;</c> | <td align="left">typedef hyper int64_t;</td> | |||
<c/> <c>Used in the definition of change_info4.</c> | </tr> | |||
<tr> | ||||
<c>clientid4</c> <c>typedef uint64_t clientid4;</c> | <td align="left">uint64_t</td> | |||
<c/> <c>Shorthand reference to client identification.</c> | <td align="left">typedef unsigned hyper uint64_t;</td> | |||
</tr> | ||||
<c>count4</c> <c>typedef uint32_t count4;</c> | <tr> | |||
<c/> <c>Various count parameters (READ, WRITE, COMMIT).</c> | <td align="left">attrlist4</td> | |||
<td align="left"><t>typedef opaque attrlist4<>;</t> | ||||
<c>length4</c> <c>typedef uint64_t length4;</c> | <t>Used for file/directory attributes.</t></td> | |||
<c/> <c>The length of a byte-range within a file.</c> | </tr> | |||
<tr> | ||||
<c>mode4</c> <c>typedef uint32_t mode4;</c> | <td align="left">bitmap4</td> | |||
<c/> <c>Mode attribute data type.</c> | <td align="left"><t>typedef uint32_t bitmap4<>;</t> | |||
<t>Used in attribute array encoding.</t> | ||||
<c>nfs_cookie4</c> <c>typedef uint64_t nfs_cookie4;</c> | </td> | |||
<c/> <c>Opaque cookie value for READDIR.</c> | </tr> | |||
<tr> | ||||
<c>nfs_fh4</c> <c>typedef opaque nfs_fh4<NFS4_FHSIZE>;</c> | <td align="left">changeid4</td> | |||
<c/> <c>Filehandle definition.</c> | <td align="left"><t>typedef uint64_t changeid4;</t> | |||
<t>Used in the definition of change_info4.</t> | ||||
<c>nfs_ftype4</c> <c>enum nfs_ftype4;</c> | </td> | |||
<c/> <c>Various defined file types.</c> | </tr> | |||
<tr> | ||||
<c>nfsstat4</c> <c>enum nfsstat4;</c> | <td align="left">clientid4</td> | |||
<c/> <c>Return value for operations.</c> | <td align="left"><t>typedef uint64_t clientid4;</t> | |||
<t>Shorthand reference to client identification.</t> | ||||
<c>offset4</c> <c>typedef uint64_t offset4;</c> | </td> | |||
<c/> <c>Various offset designations (READ, WRITE, LOCK, COMMIT).</c> | </tr> | |||
<tr> | ||||
<c>qop4</c> <c>typedef uint32_t qop4;</c> | <td align="left">count4</td> | |||
<c/> <c>Quality of protection designation in SECINFO.</c> | <td align="left"><t>typedef uint32_t count4;</t> | |||
<t>Various count parameters (READ, WRITE, | ||||
<c>sec_oid4</c> <c>typedef opaque sec_oid4<>;</c> | COMMIT).</t> | |||
<c/> <c>Security Object Identifier. The sec_oid4 data type is not rea | </td> | |||
lly opaque. Instead, it contains an ASN.1 OBJECT IDENTIFIER as used by GSS-API | </tr> | |||
in the mech_type argument to GSS_Init_sec_context. See <xref target="RFC2743" /> | <tr> | |||
for details.</c> | <td align="left">length4</td> | |||
<td align="left"><t>typedef uint64_t length4;</t> | ||||
<c>sequenceid4</c> <c>typedef uint32_t sequenceid4;</c> | <t>The length of a byte-range within a file.</t> | |||
<c/> <c>Sequence number used for various session operations (EXCHANGE_ | </td> | |||
ID, CREATE_SESSION, SEQUENCE, CB_SEQUENCE).</c> | </tr> | |||
<tr> | ||||
<c>seqid4</c> <c>typedef uint32_t seqid4;</c> | <td align="left">mode4</td> | |||
<c/> <c>Sequence identifier used for locking.</c> | <td align="left"><t>typedef uint32_t mode4;</t> | |||
<t>Mode attribute data type.</t> | ||||
<c>sessionid4</c> <c>typedef opaque sessionid4[NFS4_SESSION | </td> | |||
ID_SIZE];</c> | </tr> | |||
<c/> <c>Session identifier.</c> | <tr> | |||
<td align="left">nfs_cookie4</td> | ||||
<c>slotid4</c> <c>typedef uint32_t slotid4;</c> | <td align="left"><t>typedef uint64_t nfs_cookie4;</t> | |||
<c/> <c>Sequencing artifact for various session operations (SEQUENCE, | <t>Opaque cookie value for READDIR.</t> | |||
CB_SEQUENCE).</c> | </td> | |||
</tr> | ||||
<c>utf8string</c> <c>typedef opaque utf8string<>;</c> | <tr> | |||
<c/> <c>UTF-8 encoding for strings.</c> | <td align="left">nfs_fh4</td> | |||
<td align="left"><t>typedef opaque nfs_fh4<NFS4_FHSIZE>;</t> | ||||
<c>utf8str_cis</c> <c>typedef utf8string utf8str_cis;</c> | <t>Filehandle definition.</t> | |||
<c/> <c>Case-insensitive UTF-8 string.</c> | </td> | |||
</tr> | ||||
<c>utf8str_cs</c> <c>typedef utf8string utf8str_cs;</c> | <tr> | |||
<c/> <c>Case-sensitive UTF-8 string.</c> | <td align="left">nfs_ftype4</td> | |||
<td align="left"><t>enum nfs_ftype4;</t> | ||||
<c>utf8str_mixed</c> <c>typedef utf8string utf8str_mixed;</c> | <t>Various defined file types.</t> | |||
<c/> <c>UTF-8 strings with a case-sensitive prefix and a | </td> | |||
case-insensitive suffix.</c> | </tr> | |||
<tr> | ||||
<c>component4</c> <c>typedef utf8str_cs component4;</c> | <td align="left">nfsstat4</td> | |||
<c/> <c>Represents pathname components.</c> | <td align="left"><t>enum nfsstat4;</t> | |||
<t>Return value for operations.</t> | ||||
<c>linktext4</c> <c>typedef utf8str_cs linktext4;</c> | </td> | |||
<c/> <c>Symbolic link contents ("symbolic link" is defined in an <xref | </tr> | |||
target="symlink">Open Group</xref> standard).</c> | <tr> | |||
<td align="left">offset4</td> | ||||
<c>pathname4</c> <c>typedef component4 pathname4<>;</c> | <td align="left"><t>typedef uint64_t offset4;</t> | |||
<c/> <c>Represents pathname for fs_locations.</c> | <t>Various offset designations (READ, WRITE, LOCK, COMMIT).</t> | |||
</td> | ||||
<c>verifier4</c> <c>typedef opaque verifier4[NFS4_VERIFIER | </tr> | |||
_SIZE];</c> | <tr> | |||
<c/> <c>Verifier used for various operations (COMMIT, CREATE, EXCHANGE | <td align="left">qop4</td> | |||
_ID, OPEN, READDIR, WRITE) NFS4_VERIFIER_SIZE is defined as 8.</c> | <td align="left"><t>typedef uint32_t qop4;</t> | |||
<t>Quality of protection designation in SECINFO.</t> | ||||
<postamble>End of Base Data Types</postamble> | </td> | |||
</texttable> | </tr> | |||
</section> | <tr> | |||
<td align="left">sec_oid4</td> | ||||
<!-- start here for the structured data types --> | <td align="left"><t>typedef opaque sec_oid4<>;</t> | |||
<t>Security Object Identifier. The sec_oid4 data type is not | ||||
<section title="Structured Data Types"> | really opaque. Instead, it contains an ASN.1 OBJECT IDENTIFIER | |||
as used by GSS-API in the mech_type argument to | ||||
GSS_Init_sec_context. See <xref target="RFC2743" | ||||
format="default"/> for details.</t> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">sequenceid4</td> | ||||
<td align="left"><t>typedef uint32_t sequenceid4;</t> | ||||
<t>Sequence number used for various session operations | ||||
(EXCHANGE_ID, CREATE_SESSION, SEQUENCE, CB_SEQUENCE).</t> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">seqid4</td> | ||||
<td align="left"><t>typedef uint32_t seqid4;</t> | ||||
<t>Sequence identifier used for locking.</t> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">sessionid4</td> | ||||
<td align="left"><t>typedef opaque sessionid4[NFS4_SESSIONID_SIZE] | ||||
;</t> | ||||
<t>Session identifier.</t> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">slotid4</td> | ||||
<td align="left"><t>typedef uint32_t slotid4;</t> | ||||
<t>Sequencing artifact for various session operations | ||||
(SEQUENCE, CB_SEQUENCE).</t> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">utf8string</td> | ||||
<td align="left"><t>typedef opaque utf8string<>;</t> | ||||
<t>UTF-8 encoding for strings.</t> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">utf8str_cis</td> | ||||
<td align="left"><t>typedef utf8string utf8str_cis;</t> | ||||
<t>Case-insensitive UTF-8 string.</t> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">utf8str_cs</td> | ||||
<td align="left"><t>typedef utf8string utf8str_cs;</t> | ||||
<t>Case-sensitive UTF-8 string.</t> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">utf8str_mixed</td> | ||||
<td align="left"><t>typedef utf8string utf8str_mixed;</t> | ||||
<t>UTF-8 strings with a case-sensitive prefix and a | ||||
case-insensitive suffix.</t> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">component4</td> | ||||
<td align="left"><t>typedef utf8str_cs component4;</t> | ||||
<t>Represents pathname components.</t> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">linktext4</td> | ||||
<td align="left"><t>typedef utf8str_cs linktext4;</t> | ||||
<t>Symbolic link contents ("symbolic link" is defined in an | ||||
<xref target="symlink" format="default">Open Group</xref> | ||||
standard).</t> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">pathname4</td> | ||||
<td align="left"><t>typedef component4 pathname4<>;</t> | ||||
<t>Represents pathname for fs_locations.</t> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">verifier4</td> | ||||
<td align="left"><t>typedef opaque verifier4[NFS4_VERIFIER_SIZE];< | ||||
/t> | ||||
<t>Verifier used for various operations (COMMIT, CREATE, | ||||
EXCHANGE_ID, OPEN, READDIR, WRITE) NFS4_VERIFIER_SIZE is defined | ||||
as 8.</t> | ||||
</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
<t>End of Base Data Types</t> | ||||
</section> | ||||
<section toc="exclude" anchor="nfstime4" title="nfstime4"> | <section numbered="true" toc="default"> | |||
<figure> | <name>Structured Data Types</name> | |||
<artwork> | <section toc="exclude" anchor="nfstime4" numbered="true"> | |||
<name>nfstime4</name> | ||||
<sourcecode type="xdr"><![CDATA[ | ||||
struct nfstime4 { | struct nfstime4 { | |||
int64_t seconds; | int64_t seconds; | |||
uint32_t nseconds; | uint32_t nseconds; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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, | |||
1970. Values less than zero for the seconds field denote | 1970. Values less than zero for the seconds field denote | |||
dates before the zero hour January 1, 1970. In both cases, the | dates before the zero hour January 1, 1970. In both cases, the | |||
nseconds field is to be added to the seconds field for the | nseconds field is to be added to the seconds field for the | |||
final time representation. For example, if the time to be | final time representation. For example, if the time to be | |||
represented is one-half second before zero hour January 1, 1970, | represented is one-half second before zero hour January 1, 1970, | |||
the seconds field would have a value of negative one (-1) and | the seconds field would have a value of negative one (-1) and | |||
the nseconds field would have a value of one-half second | the nseconds field would have a value of one-half second | |||
(500000000). Values greater than 999,999,999 for nseconds are | (500000000). Values greater than 999,999,999 for nseconds are | |||
invalid. | invalid. | |||
</t> | </t> | |||
<t> | <t> | |||
This data type is used to pass time and date information. A | This data type is used to pass time and date information. A | |||
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 RECOMMENDED 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" title="time_how4"> | <name>time_how4</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
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 | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="settime4" numbered="true"> | |||
<name>settime4</name> | ||||
<section toc="exclude" anchor="settime4" title="settime4"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
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; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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_SE RVER_TIME4, then the server | for setting timestamps in file object attributes. If set_it is SET_TO_SE RVER_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" title="specdata4"> | <name>specdata4</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
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 */ | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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" title="fsid4"> | <name>fsid4</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct fsid4 { | struct fsid4 { | |||
uint64_t major; | uint64_t major; | |||
uint64_t minor; | uint64_t minor; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="chg_policy4" numbered="true"> | |||
<name>change_policy4</name> | ||||
<section toc="exclude" anchor="chg_policy4" title="change_policy4"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
struct change_policy4 { | struct change_policy4 { | |||
uint64_t cp_major; | uint64_t cp_major; | |||
uint64_t cp_minor; | uint64_t cp_minor; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
<t> | ||||
The change_policy4 data type is used for the change_policy | The change_policy4 data type is used for the change_policy | |||
RECOMMENDED attribute. It provides change sequencing indication | <bcp14>RECOMMENDED</bcp14> attribute. It provides change sequencing in dication | |||
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" title="fattr4"> | <name>fattr4</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct fattr4 { | struct fattr4 { | |||
bitmap4 attrmask; | bitmap4 attrmask; | |||
attrlist4 attr_vals; | attrlist4 attr_vals; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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> | |||
<t> | ||||
<figure> | <artwork name="" type="" align="left" alt=""><![CDATA[ | |||
<artwork> | 0 1 | |||
0 1 | ||||
+-----------+-----------+-----------+-- | +-----------+-----------+-----------+-- | |||
| count | 31 .. 0 | 63 .. 32 | | | count | 31 .. 0 | 63 .. 32 | | |||
+-----------+-----------+-----------+-- | +-----------+-----------+-----------+-- | |||
</artwork> | ]]></artwork> | |||
</figure> | </section> | |||
</t> | <section toc="exclude" anchor="change_info4" numbered="true"> | |||
</section> | <name>change_info4</name> | |||
<sourcecode type="xdr"><![CDATA[ | ||||
<section toc="exclude" anchor="change_info4" title="change_info4"> | ||||
<figure> | ||||
<artwork> | ||||
struct change_info4 { | struct change_info4 { | |||
bool atomic; | bool atomic; | |||
changeid4 before; | changeid4 before; | |||
changeid4 after; | changeid4 after; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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" title="netaddr4"> | <name>netaddr4</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
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 */ | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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"/>. The netid and uaddr formats for | <xref target="RFC5665" format="default"/>. The netid and uaddr formats fo | |||
TCP over IPv4 and TCP over IPv6 are defined in <xref target="RFC5665"/>, | r | |||
specifically Tables 2 and 3 and Sections 5.2.3.3 and 5.2.3.4. | TCP over IPv4 and TCP over IPv6 are defined in <xref target="RFC5665" fo | |||
</t> | rmat="default"/>, | |||
specifically Tables 2 and 3 and in | ||||
</section> | Sections <xref target="RFC5665" section="5.2.3.3" sectionFormat="bare"/> | |||
and <xref target="RFC5665" section="5.2.3.4" sectionFormat="bare"/>. | ||||
<section toc="exclude" anchor="state_owner4" title="state_owner4"> | </t> | |||
<figure> | </section> | |||
<artwork> | <section toc="exclude" anchor="state_owner4" numbered="true"> | |||
<name>state_owner4</name> | ||||
<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; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
<t> | ||||
The state_owner4 data type is the base type for the | The state_owner4 data type is the base type for the | |||
open_owner4 (<xref target="open_owner4" />) and | open_owner4 (<xref target="open_owner4" format="default"/>) and | |||
lock_owner4 (<xref target="lock_owner4" />). | lock_owner4 (<xref target="lock_owner4" format="default"/>). | |||
</t> | </t> | |||
<section toc="exclude" anchor="open_owner4" numbered="true"> | ||||
<section toc="exclude" anchor="open_owner4" title="open_owner4"> | <name>open_owner4</name> | |||
<t> | <t> | |||
This data type is used to identify the owner of OPEN state. | This data type is used to identify the owner of OPEN state. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="lock_owner4" numbered="true"> | ||||
<section toc="exclude" anchor="lock_owner4" title="lock_owner4"> | <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" | <name>open_to_lock_owner4</name> | |||
title="open_to_lock_owner4"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
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; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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" title="stateid4"> | <name>stateid4</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct stateid4 { | struct stateid4 { | |||
uint32_t seqid; | uint32_t seqid; | |||
opaque other[12]; | opaque other[12]; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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" title="layouttype4"> | <name>layouttype4</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
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 | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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 | |||
system attribute (<xref target="attrdef_fs_layout_type" />). | system attribute (<xref target="attrdef_fs_layout_type" format="default"/ >). | |||
A client asks for layouts of a particular type in LAYOUTGET, | A client asks for layouts of a particular type in LAYOUTGET, | |||
and processes those layouts in its layout-type-specific logic. | and processes those layouts in its layout-type-specific logic. | |||
</t> | </t> | |||
<t> | <t> | |||
The layouttype4 data type is 32 bits in length. The range | The layouttype4 data type is 32 bits in length. The range | |||
represented by the layout type is split into three parts. Type | represented by the layout type is split into three parts. Type | |||
0x0 is reserved. Types | 0x0 is reserved. Types | |||
within the range 0x00000001-0x7FFFFFFF are globally unique and | within the range 0x00000001-0x7FFFFFFF are globally unique and | |||
are assigned according to the description in <xref | are assigned according to the description in <xref target="pnfsiana" form | |||
target="pnfsiana" />; they are maintained by IANA. Types | at="default"/>; they are maintained by IANA. Types | |||
within the range 0x80000000-0xFFFFFFFF are site specific and | within the range 0x80000000-0xFFFFFFFF are site specific and | |||
for private use only. | for private use only. | |||
</t> | </t> | |||
<t> | <t> | |||
The LAYOUT4_NFSV4_1_FILES enumeration specifies that the NFSv4.1 | The LAYOUT4_NFSV4_1_FILES enumeration specifies that the NFSv4.1 | |||
file layout type, as defined in <xref target="file_layout_type" />, is to be used. The LAYOUT4_OSD2_OBJECTS | file layout type, as defined in <xref target="file_layout_type" format="d efault"/>, 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" />, 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" />, 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" title="deviceid4"> | <name>deviceid4</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
const NFS4_DEVICEID4_SIZE = 16; | const NFS4_DEVICEID4_SIZE = 16; | |||
typedef opaque deviceid4[NFS4_DEVICEID4_SIZE]; | typedef opaque deviceid4[NFS4_DEVICEID4_SIZE]; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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" | ID and layout type. See <xref target="device_ids" format="default"/> for | |||
/> for more details. | more details. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="device_addr4" | <section toc="exclude" anchor="device_addr4" numbered="true"> | |||
title="device_addr4"> | <name>device_addr4</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct device_addr4 { | struct device_addr4 { | |||
layouttype4 da_layout_type; | layouttype4 da_layout_type; | |||
opaque da_addr_body<>; | opaque da_addr_body<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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 | |||
interpreted based on the specified da_layout_type field. | interpreted based on the specified da_layout_type field. | |||
</t> | </t> | |||
<t> | <t> | |||
This document defines the device address for the NFSv4.1 file | This document defines the device address for the NFSv4.1 file | |||
layout (see <xref target="file_data_types" />), which | layout (see <xref target="file_data_types" format="default"/>), which | |||
identifies a storage device by network IP address and port | identifies a storage device by network IP address and port | |||
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" title="layout_content4"> | <name>layout_content4</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct layout_content4 { | struct layout_content4 { | |||
layouttype4 loc_type; | layouttype4 loc_type; | |||
opaque loc_body<>; | opaque loc_body<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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" | file layout type; see <xref target="file_data_types" format="default"/> f | |||
/> for its definition. | or its definition. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="layout4" title="layout4"> | <section toc="exclude" anchor="layout4" numbered="true"> | |||
<figure> | <name>layout4</name> | |||
<artwork> | <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; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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" | <name>layoutupdate4</name> | |||
title="layoutupdate4"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
struct layoutupdate4 { | struct layoutupdate4 { | |||
layouttype4 lou_type; | layouttype4 lou_type; | |||
opaque lou_body<>; | opaque lou_body<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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" />) operation. | LAYOUTCOMMIT (<xref target="OP_LAYOUTCOMMIT" format="default"/>) operatio n. | |||
This data type provides a channel to pass | This data type provides a channel to pass | |||
layout type specific information (in field lou_body) | layout type specific information (in field lou_body) | |||
back to the metadata server. | back to the metadata server. | |||
For example, for the block/volume layout type, this could include the | For example, for the block/volume layout type, this could include the | |||
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 MUST | 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" title="layouthint4"> | <name>layouthint4</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct layouthint4 { | struct layouthint4 { | |||
layouttype4 loh_type; | layouttype4 loh_type; | |||
opaque loh_body<>; | opaque loh_body<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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" />. | 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" />. | data type as defined in <xref target="file_data_types" format="default"/> | |||
</t> | . | |||
</section> | </t> | |||
</section> | ||||
<section toc="exclude" anchor="layoutiomode4" | <section toc="exclude" anchor="layoutiomode4" numbered="true"> | |||
title="layoutiomode4"> | <name>layoutiomode4</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
enum layoutiomode4 { | enum layoutiomode4 { | |||
LAYOUTIOMODE4_READ = 1, | LAYOUTIOMODE4_READ = 1, | |||
LAYOUTIOMODE4_RW = 2, | LAYOUTIOMODE4_RW = 2, | |||
LAYOUTIOMODE4_ANY = 3 | LAYOUTIOMODE4_ANY = 3 | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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 MUST NOT be used in | layout. While the LAYOUTIOMODE4_ANY iomode <bcp14>MUST NOT</bcp14> be us | |||
the arguments to the LAYOUTGET operation, it MAY | ed in | |||
the arguments to the LAYOUTGET operation, it <bcp14>MAY</bcp14> | ||||
be used in the arguments to the LAYOUTRETURN and CB_LAYOUTRECALL | be used in the arguments to the LAYOUTRETURN and CB_LAYOUTRECALL | |||
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 MAY | depend on the layout type being used. The storage devices <bcp14>MAY</b cp14> | |||
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" title="nfs_impl_id4"> | <name>nfs_impl_id4</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
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; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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 RECOMMENDED 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" title="threshold_item4"> | <name>threshold_item4</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
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<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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 | |||
server versus the storage devices. The data type | server versus the storage devices. The data type | |||
consists of the layout type (thi_layout_type), | consists of the layout type (thi_layout_type), | |||
a bitmap (thi_hintset) describing the set of | a bitmap (thi_hintset) describing the set of | |||
hints supported by the server (they may differ | hints supported by the server (they may differ | |||
based on the layout type), and a list of hints | based on the layout type), and a list of hints | |||
(thi_hintlist) whose content is determined by | (thi_hintlist) whose content is determined by | |||
the hintset bitmap. See the mdsthreshold attribute | the hintset bitmap. See the mdsthreshold attribute | |||
for more details. | for more details. | |||
</t> | </t> | |||
<t> | <t> | |||
The thi_hintset field is a bitmap of the following values: | The thi_hintset field is a bitmap of the following values: | |||
</t> | </t> | |||
<texttable> | <table align="center" anchor="table2"> | |||
<ttcol align='left'>name</ttcol> | <thead> | |||
<ttcol align='left'>#</ttcol> | <tr> | |||
<ttcol align='left'>Data Type</ttcol> | <th align="left">name</th> | |||
<ttcol align='left'>Description</ttcol> | <th align="left">#</th> | |||
<th align="left">Data Type</th> | ||||
<c>threshold4_read_size</c><c>0</c><c>length4</c> | <th align="left">Description</th> | |||
<c> | </tr> | |||
</thead> | ||||
<tbody> | ||||
<tr> | ||||
<td align="left">threshold4_read_size</td> | ||||
<td align="left">0</td> | ||||
<td align="left">length4</td> | ||||
<td align="left"> | ||||
If a file's length is less than the value of threshold4_read_size, | If a file's length is less than the value of threshold4_read_size, | |||
then it is RECOMMENDED that the client read from the file via the MDS and not | then it is <bcp14>RECOMMENDED</bcp14> that the client read from the f ile via the MDS and not | |||
a storage device. | a storage device. | |||
</c> | </td> | |||
<c>threshold4_write_size</c><c>1</c><c>length4</c> | </tr> | |||
<c> | <tr> | |||
<td align="left">threshold4_write_size</td> | ||||
<td align="left">1</td> | ||||
<td align="left">length4</td> | ||||
<td align="left"> | ||||
If a file's length is less than the value of threshold4_write_size, | If a file's length is less than the value of threshold4_write_size, | |||
then it is RECOMMENDED that the client write to the file via the MDS and not | then it is <bcp14>RECOMMENDED</bcp14> that the client write to the fi le via the MDS and not | |||
a storage device. | a storage device. | |||
</c> | </td> | |||
<c>threshold4_read_iosize</c><c>2</c><c>length4</c> | </tr> | |||
<c> | <tr> | |||
For read I/O sizes below this threshold, it is RECOMMENDED to | <td align="left">threshold4_read_iosize</td> | |||
<td align="left">2</td> | ||||
<td align="left">length4</td> | ||||
<td align="left"> | ||||
For read I/O sizes below this threshold, it is <bcp14>RECOMMENDED</bcp | ||||
14> to | ||||
read data through the MDS. | read data through the MDS. | |||
</c> | </td> | |||
<c>threshold4_write_iosize</c><c>3</c><c>length4</c> | </tr> | |||
<c> | <tr> | |||
For write I/O sizes below this threshold, it is RECOMMENDED to | <td align="left">threshold4_write_iosize</td> | |||
<td align="left">3</td> | ||||
<td align="left">length4</td> | ||||
<td align="left"> | ||||
For write I/O sizes below this threshold, it is <bcp14>RECOMMENDED</bc | ||||
p14> to | ||||
write data through the MDS. | write data through the MDS. | |||
</c> | </td> | |||
</texttable> | </tr> | |||
</section> | </tbody> | |||
</table> | ||||
<section toc="exclude" anchor="mdsthreshold4" title="mdsthreshold4"> | </section> | |||
<figure> | <section toc="exclude" anchor="mdsthreshold4" numbered="true"> | |||
<artwork> | <name>mdsthreshold4</name> | |||
<sourcecode type="xdr"><![CDATA[ | ||||
struct mdsthreshold4 { | struct mdsthreshold4 { | |||
threshold_item4 mth_hints<>; | threshold_item4 mth_hints<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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 anchor="Filehandles" numbered="true" toc="default"> | ||||
</section> | <name>Filehandles</name> | |||
</section> | <t> | |||
<!-- End of Data Types --> | ||||
<!-- $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="Filehandles" title="Filehandles"> | ||||
<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 title="Obtaining the First Filehandle"> | <section numbered="true" toc="default"> | |||
<t> | <name>Obtaining the First Filehandle</name> | |||
<t> | ||||
The operations of the NFS protocol are defined in terms of one | The operations of the NFS protocol are defined in terms of one | |||
or more filehandles. Therefore, the client needs a filehandle | or more filehandles. Therefore, the client needs a filehandle | |||
to initiate communication with the server. With the NFSv3 | to initiate communication with the server. With the NFSv3 | |||
protocol (<xref target="RFC1813">RFC 1813</xref>), there | protocol (<xref target="RFC1813" format="default">RFC 1813</xref>), there | |||
exists an ancillary protocol to obtain this first filehandle. | exists an ancillary protocol to obtain this first filehandle. | |||
The MOUNT protocol, RPC program number 100005, provides the | The MOUNT protocol, RPC program number 100005, provides the | |||
mechanism of translating a string-based file system pathname to | mechanism of translating a string-based file system pathname to | |||
a filehandle, which can then be used by the NFS protocols. | a filehandle, which can then be used by the NFS protocols. | |||
</t> | </t> | |||
<t> | <t> | |||
The MOUNT protocol has deficiencies in the area of security and | The MOUNT protocol has deficiencies in the area of security and | |||
use via firewalls. This is one reason that the use of the | use via firewalls. This is one reason that the use of the | |||
public filehandle was introduced in <xref | public filehandle was introduced in <xref target="RFC2054" format="default | |||
target="RFC2054">RFC 2054</xref> and <xref | ">RFC 2054</xref> and <xref target="RFC2055" format="default">RFC 2055</xref>. | |||
target="RFC2055">RFC 2055</xref>. With the use of the public | With the use of the public | |||
filehandle in combination with the LOOKUP operation in the NFSv3 | filehandle in combination with the LOOKUP operation in the NFSv3 | |||
protocol, it has been demonstrated that the | protocol, it has been demonstrated that the | |||
MOUNT protocol is unnecessary for viable interaction between NFS | MOUNT protocol is unnecessary for viable interaction between NFS | |||
client and server. | client and server. | |||
</t> | </t> | |||
<t> | <t> | |||
Therefore, the NFSv4.1 protocol will not use an ancillary | Therefore, the NFSv4.1 protocol will not use an ancillary | |||
protocol for translation from string-based pathnames to a filehandle. | protocol for translation from string-based pathnames to a filehandle. | |||
Two special filehandles will be used as starting points for the NFS | Two special filehandles will be used as starting points for the NFS | |||
client. | client. | |||
</t> | </t> | |||
<section title="Root Filehandle"> | <section numbered="true" toc="default"> | |||
<t> | <name>Root Filehandle</name> | |||
<t> | ||||
The first of the special filehandles is the ROOT filehandle. The ROOT | The first of the special filehandles is the ROOT filehandle. The ROOT | |||
filehandle is the "conceptual" root of the file system namespace at | filehandle is the "conceptual" root of the file system namespace at | |||
the NFS server. The client uses or starts with the ROOT filehandle | the NFS server. The client uses or starts with the ROOT filehandle | |||
by employing the PUTROOTFH operation. The PUTROOTFH operation | by employing the PUTROOTFH operation. The PUTROOTFH operation | |||
instructs the server to set the "current" filehandle to the ROOT of | instructs the server to set the "current" filehandle to the ROOT of | |||
the server's file tree. Once this PUTROOTFH operation is used, the | the server's file tree. Once this PUTROOTFH operation is used, the | |||
client can then traverse the entirety of the server's file tree with | client can then traverse the entirety of the server's file tree with | |||
the LOOKUP operation. A complete discussion of the server namespace | the LOOKUP operation. A complete discussion of the server namespace | |||
is in <xref target="single_server_namespace"/>. | is in <xref target="single_server_namespace" format="default"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Public Filehandle"> | <section numbered="true" toc="default"> | |||
<t> | <name>Public Filehandle</name> | |||
<t> | ||||
The second special filehandle is the PUBLIC filehandle. Unlike the | The second special filehandle is the PUBLIC filehandle. Unlike the | |||
ROOT filehandle, the PUBLIC filehandle may be bound or represent an | ROOT filehandle, the PUBLIC filehandle may be bound or represent an | |||
arbitrary file system object at the server. The server is responsible | arbitrary file system object at the server. The server is responsible | |||
for this binding. It may be that the PUBLIC filehandle and the ROOT | for this binding. It may be that the PUBLIC filehandle and the ROOT | |||
filehandle refer to the same file system object. However, it is up to | filehandle refer to the same file system object. However, it is up to | |||
the administrative software at the server and the policies of the | the administrative software at the server and the policies of the | |||
server administrator to define the binding of the PUBLIC filehandle | server administrator to define the binding of the PUBLIC filehandle | |||
and server file system object. The client may not make any | and server file system object. The client may not make any | |||
assumptions about this binding. The client uses the PUBLIC filehandle | assumptions about this binding. The client uses the PUBLIC filehandle | |||
via the PUTPUBFH operation. | via the PUTPUBFH operation. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section title="Filehandle Types"> | <section numbered="true" toc="default"> | |||
<t> | <name>Filehandle Types</name> | |||
<t> | ||||
In the NFSv3 protocol, there was one type of filehandle | In the NFSv3 protocol, there was one type of filehandle | |||
with a single set of semantics. This type of filehandle is termed | with a single set of semantics. This type of filehandle is termed | |||
"persistent" in NFSv4.1. The semantics of a persistent | "persistent" in NFSv4.1. The semantics of a persistent | |||
filehandle remain the same as before. A new type of filehandle | filehandle remain the same as before. A new type of filehandle | |||
introduced in NFSv4.1 is the "volatile" filehandle, which | introduced in NFSv4.1 is the "volatile" filehandle, which | |||
attempts to accommodate certain server environments. | attempts to accommodate certain server environments. | |||
</t> | </t> | |||
<t> | <t> | |||
The volatile filehandle type was introduced to address server | The volatile filehandle type was introduced to address server | |||
functionality or implementation issues that make correct | functionality or implementation issues that make correct | |||
implementation of a persistent filehandle infeasible. Some server | implementation of a persistent filehandle infeasible. Some server | |||
environments do not provide a file-system-level invariant that can be | environments do not provide a file-system-level invariant that can be | |||
used to construct a persistent filehandle. The underlying server | used to construct a persistent filehandle. The underlying server | |||
file system may not provide the invariant or the server's file system | file system may not provide the invariant or the server's file system | |||
programming interfaces may not provide access to the needed invariant. | programming interfaces may not provide access to the needed invariant. | |||
Volatile filehandles may ease the implementation of server | Volatile filehandles may ease the implementation of server | |||
functionality such as hierarchical storage management or file system | functionality such as hierarchical storage management or file system | |||
reorganization or migration. However, the volatile filehandle | reorganization or migration. However, the volatile filehandle | |||
increases the implementation burden for the client. | increases the implementation burden for the client. | |||
</t> | </t> | |||
<t> | <t> | |||
Since the client will need to handle persistent and volatile | Since the client will need to handle persistent and volatile | |||
filehandles differently, a file attribute is defined that may be used | filehandles differently, a file attribute is defined that may be used | |||
by the client to determine the filehandle types being returned by the | by the client to determine the filehandle types being returned by the | |||
server. | server. | |||
</t> | </t> | |||
<section title="General Properties of a Filehandle"> | <section numbered="true" toc="default"> | |||
<t> | <name>General Properties of a Filehandle</name> | |||
<t> | ||||
The filehandle contains all the information the | The filehandle contains all the information the | |||
server needs to distinguish an individual file. | server needs to distinguish an individual file. | |||
To the client, the filehandle is opaque. The | To the client, the filehandle is opaque. The | |||
client stores filehandles for use in a later | client stores filehandles for use in a later | |||
request and can compare two filehandles from the | request and can compare two filehandles from the | |||
same server for equality by doing a byte-by-byte | same server for equality by doing a byte-by-byte | |||
comparison. However, the client MUST NOT otherwise | comparison. However, the client <bcp14>MUST NOT</bcp14> otherwise | |||
interpret the contents of filehandles. If two | interpret the contents of filehandles. If two | |||
filehandles from the same server are equal, they | filehandles from the same server are equal, they | |||
MUST refer to the same file. Servers SHOULD try | <bcp14>MUST</bcp14> refer to the same file. Servers <bcp14>SHOULD</bcp1 4> try | |||
to maintain a one-to-one correspondence between | to maintain a one-to-one correspondence between | |||
filehandles and files, but this is not required. | filehandles and files, but this is not required. | |||
Clients MUST use filehandle comparisons only to | Clients <bcp14>MUST</bcp14> use filehandle comparisons only to | |||
improve performance, not for correct behavior. | improve performance, not for correct behavior. | |||
All clients need to be prepared for situations | All clients need to be prepared for situations | |||
in which it cannot be determined whether two | in which it cannot be determined whether two | |||
filehandles denote the same object and in such | filehandles denote the same object and in such | |||
cases, avoid making invalid assumptions that might | cases, avoid making invalid assumptions that might | |||
cause incorrect behavior. Further discussion | cause incorrect behavior. Further discussion | |||
of filehandle and attribute comparison in the | of filehandle and attribute comparison in the | |||
context of data caching is presented in <xref | context of data caching is presented in <xref target="data_caching_and_f | |||
target="data_caching_and_file_identity"/>. | ile_identity" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
As an example, in the case that two different pathnames when | As an example, in the case that two different pathnames when | |||
traversed at the server terminate at the same file system object, the | traversed at the server terminate at the same file system object, the | |||
server SHOULD return the same filehandle for each path. This can | server <bcp14>SHOULD</bcp14> return the same filehandle for each path. | |||
occur if a hard link (see <xref target="hardlink"/>) is used | This can | |||
occur if a hard link (see <xref target="hardlink" format="default"/>) is | ||||
used | ||||
to create two file names that refer to the same underlying | to create two file names that refer to the same underlying | |||
file object and associated data. For example, if paths /a/b/c | file object and associated data. For example, if paths /a/b/c | |||
and /a/d/c refer to the same file, the server SHOULD return | and /a/d/c refer to the same file, the server <bcp14>SHOULD</bcp14> retu rn | |||
the same filehandle for both pathnames' traversals. | the same filehandle for both pathnames' traversals. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Persistent Filehandle"> | <section numbered="true" toc="default"> | |||
<t> | <name>Persistent Filehandle</name> | |||
<t> | ||||
A persistent filehandle is defined as having a fixed value for the | A persistent filehandle is defined as having a fixed value for the | |||
lifetime of the file system object to which it refers. Once the | lifetime of the file system object to which it refers. Once the | |||
server creates the filehandle for a file system object, the server | server creates the filehandle for a file system object, the server | |||
MUST accept the same filehandle for the object for the lifetime of the | <bcp14>MUST</bcp14> accept the same filehandle for the object for the li | |||
object. If the server restarts, the NFS server MUST honor | fetime of the | |||
object. If the server restarts, the NFS server <bcp14>MUST</bcp14> hono | ||||
r | ||||
the same filehandle value as it did in the server's previous | the same filehandle value as it did in the server's previous | |||
instantiation. Similarly, if the file system is migrated, the new NFS | instantiation. Similarly, if the file system is migrated, the new NFS | |||
server MUST honor the same filehandle as the old NFS server. | server <bcp14>MUST</bcp14> honor the same filehandle as the old NFS serv | |||
</t> | er. | |||
<t> | </t> | |||
<t> | ||||
The persistent filehandle will be become stale or invalid when the | The persistent filehandle will be become stale or invalid when the | |||
file system object is removed. When the server is presented with a | file system object is removed. When the server is presented with a | |||
persistent filehandle that refers to a deleted object, it MUST return | persistent filehandle that refers to a deleted object, it <bcp14>MUST</b cp14> return | |||
an error of NFS4ERR_STALE. A filehandle may become stale when the | an error of NFS4ERR_STALE. A filehandle may become stale when the | |||
file system containing the object is no longer available. The file | file system containing the object is no longer available. The file | |||
system may become unavailable if it exists on removable media and the | system may become unavailable if it exists on removable media and the | |||
media is no longer available at the server or the file system in whole | media is no longer available at the server or the file system in whole | |||
has been destroyed or the file system has simply been removed from the | has been destroyed or the file system has simply been removed from the | |||
server's namespace (i.e., unmounted in a UNIX environment). | server's namespace (i.e., unmounted in a UNIX environment). | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Volatile Filehandle"> | <section numbered="true" toc="default"> | |||
<t> | <name>Volatile Filehandle</name> | |||
<t> | ||||
A volatile filehandle does not share the same longevity | A volatile filehandle does not share the same longevity | |||
characteristics of a persistent filehandle. The server may | characteristics of a persistent filehandle. The server may | |||
determine that a volatile filehandle is no longer valid at many | determine that a volatile filehandle is no longer valid at many | |||
different points in time. If the server can definitively determine | different points in time. If the server can definitively determine | |||
that a volatile filehandle refers to an object that has been removed, | that a volatile filehandle refers to an object that has been removed, | |||
the server should return NFS4ERR_STALE to the client (as is the case | the server should return NFS4ERR_STALE to the client (as is the case | |||
for persistent filehandles). In all other cases where the server | for persistent filehandles). In all other cases where the server | |||
determines that a volatile filehandle can no longer be used, it should | determines that a volatile filehandle can no longer be used, it should | |||
return an error of NFS4ERR_FHEXPIRED. | return an error of NFS4ERR_FHEXPIRED. | |||
</t> | </t> | |||
<t> | <t> | |||
The REQUIRED attribute "fh_expire_type" is used by the client to | The <bcp14>REQUIRED</bcp14> attribute "fh_expire_type" is used by the cl | |||
ient to | ||||
determine what type of filehandle the server is providing for a | determine what type of filehandle the server is providing for a | |||
particular file system. This attribute is a bitmask with the | particular file system. This attribute is a bitmask with the | |||
following values: | following values: | |||
</t> | </t> | |||
<t> | <dl newline="false" spacing="normal"> | |||
<list style="hanging"> | <dt>FH4_PERSISTENT</dt> | |||
<t hangText="FH4_PERSISTENT"> | <dd> | |||
The value of FH4_PERSISTENT is used to indicate a persistent | The value of FH4_PERSISTENT is used to indicate a persistent | |||
filehandle, which is valid until the object is removed from the | filehandle, which is valid until the object is removed from the | |||
file system. The server will not return NFS4ERR_FHEXPIRED for this | file system. The server will not return NFS4ERR_FHEXPIRED for this | |||
filehandle. FH4_PERSISTENT is defined as a value in which none of t he | filehandle. FH4_PERSISTENT is defined as a value in which none of t he | |||
bits specified below are set. | bits specified below are set. | |||
</t> | </dd> | |||
<t hangText="FH4_VOLATILE_ANY"> | <dt>FH4_VOLATILE_ANY</dt> | |||
<dd> | ||||
The filehandle may expire at any time, except as specifically | The filehandle may expire at any time, except as specifically | |||
excluded (i.e., FH4_NO_EXPIRE_WITH_OPEN). | excluded (i.e., FH4_NO_EXPIRE_WITH_OPEN). | |||
</t> | </dd> | |||
<t hangText="FH4_NOEXPIRE_WITH_OPEN"> | <dt>FH4_NOEXPIRE_WITH_OPEN</dt> | |||
<dd> | ||||
May only be set when FH4_VOLATILE_ANY is set. If this bit is set, | May only be set when FH4_VOLATILE_ANY is set. If this bit is set, | |||
then the meaning of FH4_VOLATILE_ANY is qualified to exclude any | then the meaning of FH4_VOLATILE_ANY is qualified to exclude any | |||
expiration of the filehandle when it is open. | expiration of the filehandle when it is open. | |||
</t> | </dd> | |||
<t hangText="FH4_VOL_MIGRATION"> | <dt>FH4_VOL_MIGRATION</dt> | |||
<dd> | ||||
The filehandle will expire as a result of a file system | The filehandle will expire as a result of a file system | |||
transition (migration or replication), in those cases in | transition (migration or replication), in those cases in | |||
which the continuity of filehandle use is not specified by | which the continuity of filehandle use is not specified by | |||
handle class information | handle class information | |||
within the fs_locations_info attribute. When this bit is | within the fs_locations_info attribute. When this bit is | |||
set, clients without access to fs_locations_info | set, clients without access to fs_locations_info | |||
information should assume that filehandles will expire on file | information should assume that filehandles will expire on file | |||
system transitions. | system transitions. | |||
</t> | </dd> | |||
<t hangText="FH4_VOL_RENAME"> | <dt>FH4_VOL_RENAME</dt> | |||
<dd> | ||||
The filehandle will expire during rename. This includes a rename by | The filehandle will expire during rename. This includes a rename by | |||
the requesting client or a rename by any other client. If FH4_VOL_A NY | the requesting client or a rename by any other client. If FH4_VOL_A NY | |||
is set, FH4_VOL_RENAME is redundant. | is set, FH4_VOL_RENAME is redundant. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | <t> | |||
<t> | ||||
Servers that provide volatile filehandles that can expire | Servers that provide volatile filehandles that can expire | |||
while open require special care as regards handling of RENAMEs | while open require special care as regards handling of RENAMEs | |||
and REMOVEs. This situation can arise if FH4_VOL_MIGRATION or | and REMOVEs. This situation can arise if FH4_VOL_MIGRATION or | |||
FH4_VOL_RENAME is set, if FH4_VOLATILE_ANY is set and | FH4_VOL_RENAME is set, if FH4_VOLATILE_ANY is set and | |||
FH4_NOEXPIRE_WITH_OPEN is not set, or if a non-read-only file system | FH4_NOEXPIRE_WITH_OPEN is not set, or if a non-read-only file system | |||
has a transition target in a different handle | has a transition target in a different handle | |||
class. In these cases, the server should deny a RENAME | class. In these cases, the server should deny a RENAME | |||
or REMOVE that would affect an OPEN file of any of the | or REMOVE that would affect an OPEN file of any of the | |||
components leading to the OPEN file. In addition, the server | components leading to the OPEN file. In addition, the server | |||
should deny all RENAME or REMOVE requests during the grace period, | should deny all RENAME or REMOVE requests during the grace period, | |||
in order to make sure that reclaims of files where filehandles | in order to make sure that reclaims of files where filehandles | |||
may have expired do not do a reclaim for the wrong file. | may have expired do not do a reclaim for the wrong file. | |||
</t> | </t> | |||
<t> | <t> | |||
Volatile filehandles are especially suitable for implementation | Volatile filehandles are especially suitable for implementation | |||
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" /> for a discussion of this. | <xref target="pseudo_fs_volatility" format="default"/> for a discussion | |||
</t> | of this. | |||
</section> | </t> | |||
</section> | </section> | |||
<section title="One Method of Constructing a Volatile Filehandle"> | </section> | |||
<t> | <section numbered="true" toc="default"> | |||
<name>One Method of Constructing a Volatile Filehandle</name> | ||||
<t> | ||||
A volatile filehandle, while opaque to the client, could contain: | A volatile filehandle, while opaque to the client, could contain: | |||
</t> | </t> | |||
<figure> | <sourcecode type="pseudocode"><![CDATA[ | |||
<artwork> | ||||
[volatile bit = 1 | server boot time | slot | generation number] | [volatile bit = 1 | server boot time | slot | generation number] | |||
o slot is an index in the server volatile filehandle table | ]]></sourcecode> | |||
<ul> | ||||
o generation number is the generation number for the table entry/ | <li>slot is an index in the server volatile filehandle table</li> | |||
slot | <li>generation number is the generation number for the table entry/slot</li> | |||
</artwork> | </ul> | |||
</figure> | <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 | |||
time, return NFS4ERR_FHEXPIRED. If slot is out of range, return | time, return NFS4ERR_FHEXPIRED. If slot is out of range, return | |||
NFS4ERR_BADHANDLE. If the generation number does not match, return | NFS4ERR_BADHANDLE. If the generation number does not match, return | |||
NFS4ERR_FHEXPIRED. | NFS4ERR_FHEXPIRED. | |||
</t> | </t> | |||
<t> | <t> | |||
When the server restarts, the table is gone (it is volatile). | When the server restarts, the table is gone (it is volatile). | |||
</t> | </t> | |||
<t> | <t> | |||
If the volatile bit is 0, then it is a persistent filehandle with a | If the volatile bit is 0, then it is a persistent filehandle with a | |||
different structure following it. | different structure following it. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="Client Recovery from Filehandle Expiration"> | <name>Client Recovery from Filehandle Expiration</name> | |||
<t> | <t> | |||
If possible, the client SHOULD recover from the receipt of an | If possible, the client <bcp14>SHOULD</bcp14> recover from the receipt of | |||
an | ||||
NFS4ERR_FHEXPIRED error. The client must take on additional | NFS4ERR_FHEXPIRED error. The client must take on additional | |||
responsibility so that it may prepare itself to recover from the | responsibility so that it may prepare itself to recover from the | |||
expiration of a volatile filehandle. If the server returns persistent | expiration of a volatile filehandle. If the server returns persistent | |||
filehandles, the client does not need these additional steps. | filehandles, the client does not need these additional steps. | |||
</t> | </t> | |||
<t> | <t> | |||
For volatile filehandles, most commonly the client will need to store | For volatile filehandles, most commonly the client will need to store | |||
the component names leading up to and including the file system object | the component names leading up to and including the file system object | |||
in question. With these names, the client should be able to recover | in question. With these names, the client should be able to recover | |||
by finding a filehandle in the namespace that is still available or | by finding a filehandle in the namespace that is still available or | |||
by starting at the root of the server's file system namespace. | by starting at the root of the server's file system namespace. | |||
</t> | </t> | |||
<t> | <t> | |||
If the expired filehandle refers to an object that has been removed | If the expired filehandle refers to an object that has been removed | |||
from the file system, obviously the client will not be able to recover | from the file system, obviously the client will not be able to recover | |||
from the expired filehandle. | from the expired filehandle. | |||
</t> | </t> | |||
<t> | <t> | |||
It is also possible that the expired filehandle refers to a file that | It is also possible that the expired filehandle refers to a file that | |||
has been renamed. If the file was renamed by another client, again 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: | |||
<figure> | </t> | |||
<artwork> | <sourcecode type="nfsv4compound"><![CDATA[ | |||
RENAME A B | RENAME A B | |||
LOOKUP B | LOOKUP B | |||
GETFH | GETFH | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="file_attributes" numbered="true" toc="default"> | |||
$ --> | <name>File Attributes</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <t> | |||
<!-- Copyright (C) The Internet Society (2006) --> | ||||
<section anchor="file_attributes" title="File Attributes"> | ||||
<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 | |||
the server supports and construct requests with only those supported | the server supports and construct requests with only those supported | |||
attributes (or a subset thereof). | attributes (or a subset thereof). | |||
</t> | </t> | |||
<t> | <t> | |||
To this end, attributes are divided into three groups: REQUIRED, | To this end, attributes are divided into three groups: <bcp14>REQUIRED</bcp1 | |||
RECOMMENDED, and named. Both REQUIRED and RECOMMENDED attributes are | 4>, | |||
<bcp14>RECOMMENDED</bcp14>, and named. Both <bcp14>REQUIRED</bcp14> and <bc | ||||
p14>RECOMMENDED</bcp14> attributes are | ||||
supported in the NFSv4.1 protocol by a specific and well-defined | supported in the NFSv4.1 protocol by a specific and well-defined | |||
encoding and are identified by number. They are requested by setting | encoding and are identified by number. They are requested by setting | |||
a bit in the bit vector sent in the GETATTR request; the server | a bit in the bit vector sent in the GETATTR request; the server | |||
response includes a bit vector to list what attributes were returned | response includes a bit vector to list what attributes were returned | |||
in the response. New REQUIRED or RECOMMENDED attributes may be added | in the response. New <bcp14>REQUIRED</bcp14> or <bcp14>RECOMMENDED</bcp14> attributes may be added | |||
to the NFSv4 protocol as part of a new minor version | to the NFSv4 protocol as part of a new minor version | |||
by publishing a | by publishing a | |||
Standards Track RFC that allocates a new attribute number value and | Standards Track RFC that allocates a new attribute number value and | |||
defines the encoding for the attribute. See | defines the encoding for the attribute. See | |||
<xref target="minor_versioning"/> for further | <xref target="minor_versioning" format="default"/> for further | |||
discussion. | discussion. | |||
</t> | </t> | |||
<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> | |||
<texttable> | <table align="center" anchor="table3"> | |||
<ttcol align='left' /> | <tbody> | |||
<ttcol align='left' /> | <tr> | |||
<ttcol align='left' /> | <td align="left">LOOKUP</td> | |||
<c>LOOKUP</c><c>"foo"</c><c>; look up file</c> | <td align="left">"foo"</td> | |||
<c>GETATTR</c><c>attrbits</c><c /> | <td align="left">; look up file</td> | |||
<c>OPENATTR</c><c /><c>; access foo's named attributes</c> | </tr> | |||
<c>LOOKUP</c><c>"x11icon"</c><c>; look up specific attribute</c> | <tr> | |||
<c>READ</c><c>0,4096</c><c>; read stream of bytes</c> | <td align="left">GETATTR</td> | |||
</texttable> | <td align="left">attrbits</td> | |||
<t> | <td align="left"/> | |||
</tr> | ||||
<tr> | ||||
<td align="left">OPENATTR</td> | ||||
<td align="left"/> | ||||
<td align="left">; access foo's named attributes</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">LOOKUP</td> | ||||
<td align="left">"x11icon"</td> | ||||
<td align="left">; look up specific attribute</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">READ</td> | ||||
<td align="left">0,4096</td> | ||||
<td align="left">; read stream of bytes</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
<t> | ||||
Named attributes are intended for data needed by applications rather | Named attributes are intended for data needed by applications rather | |||
than by an NFS client implementation. NFS implementors are strongly | than by an NFS client implementation. NFS implementors are strongly | |||
encouraged to define their new attributes as RECOMMENDED attributes by | encouraged to define their new attributes as <bcp14>RECOMMENDED</bcp14> attr ibutes by | |||
bringing them to the IETF Standards Track process. | bringing them to the IETF Standards Track process. | |||
</t> | </t> | |||
<t> | <t> | |||
The set of attributes that are classified as REQUIRED is | The set of attributes that are classified as <bcp14>REQUIRED</bcp14> is | |||
deliberately small since servers need to do whatever it takes to support | deliberately small since servers need to do whatever it takes to support | |||
them. A server should support as many of the RECOMMENDED attributes | them. A server should support as many of the <bcp14>RECOMMENDED</bcp14> att ributes | |||
as possible but, by their definition, the server is not required to | as possible but, by their definition, the server is not required to | |||
support all of them. Attributes are deemed REQUIRED if the data is | support all of them. Attributes are deemed <bcp14>REQUIRED</bcp14> if the d ata is | |||
both needed by a large number of clients and is not otherwise | both needed by a large number of clients and is not otherwise | |||
reasonably computable by the client when support is not provided on | reasonably computable by the client when support is not provided on | |||
the server. | the server. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that the hidden directory returned by OPENATTR is a convenience | Note that the hidden directory returned by OPENATTR is a convenience | |||
for protocol processing. The client should not make any assumptions | for protocol processing. The client should not make any assumptions | |||
about the server's implementation of named attributes and whether | about the server's implementation of named attributes and whether | |||
or not the underlying file system at the server has a named | or not the underlying file system at the server has a named | |||
attribute directory. Therefore, operations such as SETATTR and | attribute directory. Therefore, operations such as SETATTR and | |||
GETATTR on the named attribute directory are undefined. | GETATTR on the named attribute directory are undefined. | |||
</t> | </t> | |||
<section anchor="mandatory_attributes_intro" title="REQUIRED Attributes"> | <section anchor="mandatory_attributes_intro" numbered="true" toc="default" | |||
<t> | > | |||
These MUST be supported by every NFSv4.1 client and server in | <name><bcp14>REQUIRED</bcp14> Attributes</name> | |||
order to ensure a minimum level of interoperability. The server MUST | <t> | |||
store and return these attributes, and the client MUST be able to | These <bcp14>MUST</bcp14> be supported by every NFSv4.1 client and server | |||
in | ||||
order to ensure a minimum level of interoperability. The server <bcp14>MU | ||||
ST</bcp14> | ||||
store and return these attributes, and the client <bcp14>MUST</bcp14> be a | ||||
ble to | ||||
function with an attribute set limited to these attributes. With just | function with an attribute set limited to these attributes. With just | |||
the REQUIRED attributes some client functionality may be impaired or | the <bcp14>REQUIRED</bcp14> attributes some client functionality may be im paired or | |||
limited in some ways. A client may ask for any of these attributes to | limited in some ways. A client may ask for any of these attributes to | |||
be returned by setting a bit in the GETATTR request, and the server | be returned by setting a bit in the GETATTR request, and the server | |||
MUST return their value. | <bcp14>MUST</bcp14> return their value. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="recommended_attributes_intro" title="RECOMMENDED Attributes"> | <section anchor="recommended_attributes_intro" numbered="true" toc="defaul | |||
<t> | t"> | |||
<name><bcp14>RECOMMENDED</bcp14> Attributes</name> | ||||
<t> | ||||
These attributes are understood well enough to warrant support in the | These attributes are understood well enough to warrant support in the | |||
NFSv4.1 protocol. However, they may not be supported on all | NFSv4.1 protocol. However, they may not be supported on all | |||
clients and servers. A client may ask for any of these attributes to | clients and servers. A client may ask for any of these attributes to | |||
be returned by setting a bit in the GETATTR request but must handle | be returned by setting a bit in the GETATTR request but must handle | |||
the case where the server does not return them. A client MAY ask for | the case where the server does not return them. A client <bcp14>MAY</bcp1 | |||
the set of attributes the server supports and SHOULD NOT request | 4> ask for | |||
the set of attributes the server supports and <bcp14>SHOULD NOT</bcp14> re | ||||
quest | ||||
attributes the server does not support. A server should be tolerant | attributes the server does not support. A server should be tolerant | |||
of requests for unsupported attributes and simply not return them | of requests for unsupported attributes and simply not return them | |||
rather than considering the request an error. It is expected that | rather than considering the request an error. It is expected that | |||
servers will support all attributes they comfortably can and only fail | servers will support all attributes they comfortably can and only fail | |||
to support attributes that are difficult to support in their | to support attributes that are difficult to support in their | |||
operating environments. A server should provide attributes whenever | operating environments. A server should provide attributes whenever | |||
they don't have to "tell lies" to the client. For example, a file | they don't have to "tell lies" to the client. For example, a file | |||
modification time should be either an accurate time or should not be | modification time should be either an accurate time or should not be | |||
supported by the server. At times this will be difficult for | supported by the server. At times this will be difficult for | |||
clients, but a client is better positioned to decide whether and how to | clients, but a client is better positioned to decide whether and how to | |||
fabricate or construct an attribute or whether to do without the | fabricate or construct an attribute or whether to do without the | |||
attribute. | attribute. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="named_attributes_intro" title="Named Attributes"> | <section anchor="named_attributes_intro" numbered="true" toc="default"> | |||
<t> | <name>Named Attributes</name> | |||
<t> | ||||
These attributes are not supported by direct encoding in the NFSv4 | These attributes are not supported by direct encoding in the NFSv4 | |||
protocol but are accessed by string names rather than | protocol but are accessed by string names rather than | |||
numbers and correspond to an uninterpreted stream of bytes that are | numbers and correspond to an uninterpreted stream of bytes that are | |||
stored with the file system object. The namespace for these | stored with the file system object. The namespace for these | |||
attributes may be accessed by using the OPENATTR operation. The | attributes may be accessed by using the OPENATTR operation. The | |||
OPENATTR operation returns a filehandle for a virtual "named attribute | OPENATTR operation returns a filehandle for a virtual "named attribute | |||
directory", and further perusal and modification of the namespace may | directory", and further perusal and modification of the namespace may | |||
be done using operations that work on more typical directories. In | be done using operations that work on more typical directories. In | |||
particular, READDIR may be used to get a list of such named attributes, | particular, READDIR may be used to get a list of such named attributes, | |||
and LOOKUP and OPEN may select a particular attribute. Creation of | and LOOKUP and OPEN may select a particular attribute. Creation of | |||
a new named attribute may be the result of an OPEN specifying file | a new named attribute may be the result of an OPEN specifying file | |||
creation. | creation. | |||
</t> | </t> | |||
<t> | <t> | |||
Once an OPEN is done, named attributes may be examined and changed | Once an OPEN is done, named attributes may be examined and changed | |||
by normal READ and WRITE operations using the filehandles and stateids | by normal READ and WRITE operations using the filehandles and stateids | |||
returned by OPEN. | returned by OPEN. | |||
</t> | </t> | |||
<t> | <t> | |||
Named attributes and the named attribute directory may have | Named attributes and the named attribute directory may have | |||
their own (non-named) attributes. Each of these objects MUST have all | their own (non-named) attributes. Each of these objects <bcp14>MUST</bcp1 | |||
of the REQUIRED attributes and may have additional RECOMMENDED | 4> have all | |||
of the <bcp14>REQUIRED</bcp14> attributes and may have additional <bcp14>R | ||||
ECOMMENDED</bcp14> | ||||
attributes. However, the set of attributes for named attributes | attributes. However, the set of attributes for named attributes | |||
and the named attribute directory need not be, and | and the named attribute directory need not be, and | |||
typically will not be, as large as that for other objects in that | typically will not be, as large as that for other objects in that | |||
file system. | file system. | |||
</t> | </t> | |||
<t> | <t> | |||
Named attributes and the named attribute directory might be the | Named attributes and the named attribute directory might be the | |||
target of delegations (in the case of the named attribute directory, | target of delegations (in the case of the named attribute directory, | |||
these will be directory delegations). However, since granting of | these will be directory delegations). However, since granting of | |||
delegations is at the server's discretion, a server | delegations is at the server's discretion, a server | |||
need not support delegations on named attributes or the named | need not support delegations on named attributes or the named | |||
attribute directory. | attribute directory. | |||
</t> | </t> | |||
<t> | <t> | |||
It is RECOMMENDED that servers support arbitrary named attributes. A | It is <bcp14>RECOMMENDED</bcp14> that servers support arbitrary named attr | |||
ibutes. A | ||||
client should not depend on the ability to store any named attributes | client should not depend on the ability to store any named attributes | |||
in the server's file system. If a server does support named | in the server's file system. If a server does support named | |||
attributes, a client that is also able to handle them should be able | attributes, a client that is also able to handle them should be able | |||
to copy a file's data and metadata with complete transparency from | to copy a file's data and metadata with complete transparency from | |||
one location to another; this would imply that names allowed for | one location to another; this would imply that names allowed for | |||
regular directory entries are valid for named attribute names as well. | regular directory entries are valid for named attribute names as well. | |||
</t> | </t> | |||
<t> | <t> | |||
In NFSv4.1, the structure of named attribute directories is | In NFSv4.1, the structure of named attribute directories is | |||
restricted in a number of ways, in order to prevent the development | restricted in a number of ways, in order to prevent the development | |||
of non-interoperable implementations in which some servers support | of non-interoperable implementations in which some servers support | |||
a fully general hierarchical directory structure for named attributes | a fully general hierarchical directory structure for named attributes | |||
while others support a limited but adequate structure for named attributes . | while others support a limited but adequate structure for named attributes . | |||
In such an environment, clients or applications might come to | In such an environment, clients or applications might come to | |||
depend on non-portable extensions. The restrictions are: | depend on non-portable extensions. The restrictions are: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
CREATE is not allowed in a named attribute directory. Thus, such | CREATE is not allowed in a named attribute directory. Thus, such | |||
objects as symbolic links and special files are not allowed to | objects as symbolic links and special files are not allowed to | |||
be named attributes. Further, directories may not be created | be named attributes. Further, directories may not be created | |||
in a named attribute directory, so no hierarchical structure of | in a named attribute directory, so no hierarchical structure of | |||
named attributes for a single object is allowed. | named attributes for a single object is allowed. | |||
</t> | </li> | |||
<t> | <li> | |||
If OPENATTR is done on a named attribute directory or on | If OPENATTR is done on a named attribute directory or on | |||
a named attribute, the server MUST return NFS4ERR_WRONG_TYPE. | a named attribute, the server <bcp14>MUST</bcp14> return NFS4ERR_WRONG | |||
</t> | _TYPE. | |||
<t> | </li> | |||
<li> | ||||
Doing a RENAME of a named attribute to a different named | Doing a RENAME of a named attribute to a different named | |||
attribute directory or to an ordinary (i.e., non-named-attribute) | attribute directory or to an ordinary (i.e., non-named-attribute) | |||
directory is not allowed. | directory is not allowed. | |||
</t> | </li> | |||
<t> | <li> | |||
Creating hard links between named attribute directories or | Creating hard links between named attribute directories or | |||
between named attribute directories and ordinary directories | between named attribute directories and ordinary directories | |||
is not allowed. | is not allowed. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Names of attributes will not be controlled by this document or other | Names of attributes will not be controlled by this document or other | |||
IETF Standards Track documents. See | IETF Standards Track documents. See | |||
<xref target="namedattributesiana"/> | <xref target="namedattributesiana" format="default"/> | |||
for further discussion. | for further discussion. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Classification of Attributes"> | <section numbered="true" toc="default"> | |||
<t> | <name>Classification of Attributes</name> | |||
Each of the REQUIRED and RECOMMENDED attributes can be classified in | <t> | |||
Each of the <bcp14>REQUIRED</bcp14> and <bcp14>RECOMMENDED</bcp14> attribu | ||||
tes can be classified in | ||||
one of three categories: per server (i.e., the value of the attribute will | one of three categories: per server (i.e., the value of the attribute will | |||
be the same for all file objects that share the same | be the same for all file objects that share the same | |||
server owner; see <xref target="Server_Owners"/> for a definition of serve r | server owner; see <xref target="Server_Owners" format="default"/> for a de finition of server | |||
owner), per file system (i.e., the value of the attribute will | owner), per file system (i.e., the value of the attribute will | |||
be the same for some or all file objects that share the | be the same for some or all file objects that share the | |||
same <xref target="attrdef_fsid">fsid attribute</xref> and | same <xref target="attrdef_fsid" format="default">fsid attribute</xref> an d | |||
server owner), or per file system | server owner), or per file system | |||
object. Note that it is possible that some per file system attributes | object. Note that it is possible that some per file system attributes | |||
may vary within the file system, depending on the value of | may vary within the file system, depending on the value of | |||
the <xref target="attrdef_homogeneous">"homogeneous"</xref> | the <xref target="attrdef_homogeneous" format="default">"homogeneous"</xre f> | |||
attribute. Note that the attributes time_access_set and | attribute. Note that the attributes time_access_set and | |||
time_modify_set are not listed in this section because they are | time_modify_set are not listed in this section because they are | |||
write-only attributes corresponding to time_access and time_modify, | write-only attributes corresponding to time_access and time_modify, | |||
and are used in a special instance of SETATTR. | and are used in a special instance of SETATTR. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
The per-server attribute is: | The per-server attribute is: | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
lease_time | lease_time | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
The per-file system attributes are: | The per-file system attributes are: | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
supported_attrs, suppattr_exclcreat, fh_expire_type, link_support, | supported_attrs, suppattr_exclcreat, fh_expire_type, link_support, | |||
symlink_support, unique_handles, aclsupport, | symlink_support, unique_handles, aclsupport, | |||
cansettime, case_insensitive, case_preserving, | cansettime, case_insensitive, case_preserving, | |||
chown_restricted, files_avail, files_free, | chown_restricted, files_avail, files_free, | |||
files_total, fs_locations, homogeneous, maxfilesize, | files_total, fs_locations, homogeneous, maxfilesize, | |||
maxname, maxread, maxwrite, no_trunc, space_avail, | maxname, maxread, maxwrite, no_trunc, space_avail, | |||
space_free, space_total, time_delta, | space_free, space_total, time_delta, | |||
change_policy, fs_status, | change_policy, fs_status, | |||
fs_layout_type, fs_locations_info, fs_charset_cap | fs_layout_type, fs_locations_info, fs_charset_cap | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
The per-file system object attributes are: | The per-file system object attributes are: | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
type, change, size, named_attr, fsid, rdattr_error, | type, change, size, named_attr, fsid, rdattr_error, | |||
filehandle, acl, archive, fileid, hidden, maxlink, | filehandle, acl, archive, fileid, hidden, maxlink, | |||
mimetype, mode, numlinks, owner, owner_group, rawdev, | mimetype, mode, numlinks, owner, owner_group, rawdev, | |||
space_used, system, time_access, time_backup, | space_used, system, time_access, time_backup, | |||
time_create, time_metadata, time_modify, | time_create, time_metadata, time_modify, | |||
mounted_on_fileid, dir_notif_delay, dirent_notif_delay, | mounted_on_fileid, dir_notif_delay, dirent_notif_delay, | |||
dacl, sacl, | dacl, sacl, | |||
layout_type, layout_hint, layout_blksize, layout_alignment, | layout_type, layout_hint, layout_blksize, layout_alignment, | |||
mdsthreshold, retention_get, retention_set, retentevt_get, | mdsthreshold, retention_get, retention_set, retentevt_get, | |||
retentevt_set, retention_hold, mode_set_masked | retentevt_set, retention_hold, mode_set_masked | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
For quota_avail_hard, quota_avail_soft, and quota_used, see their | For quota_avail_hard, quota_avail_soft, and quota_used, see their | |||
definitions below for the appropriate classification. | definitions below for the appropriate classification. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section anchor="rw_attr" numbered="true" toc="default"> | |||
<name>Set-Only and Get-Only Attributes</name> | ||||
<section anchor="rw_attr" | <t> | |||
title="Set-Only and Get-Only Attributes"> | Some <bcp14>REQUIRED</bcp14> and <bcp14>RECOMMENDED</bcp14> attributes are | |||
<t> | set-only; i.e., they | |||
Some REQUIRED and RECOMMENDED attributes are set-only; i.e., they | ||||
can be set via SETATTR but not retrieved via GETATTR. Similarly, some | can be set via SETATTR but not retrieved via GETATTR. Similarly, some | |||
REQUIRED and RECOMMENDED attributes are get-only; i.e., they | <bcp14>REQUIRED</bcp14> and <bcp14>RECOMMENDED</bcp14> attributes are get-o nly; i.e., they | |||
can be retrieved via GETATTR but not set via SETATTR. If a client attempts | can be retrieved via GETATTR but not set via SETATTR. If a client attempts | |||
to set a get-only attribute or get a set-only attributes, the server | to set a get-only attribute or get a set-only attributes, the server | |||
MUST return NFS4ERR_INVAL. | <bcp14>MUST</bcp14> return NFS4ERR_INVAL. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section anchor="mandatory_attributes" numbered="true" toc="default"> | |||
<name><bcp14>REQUIRED</bcp14> Attributes - List and Definition Reference | ||||
<section anchor="mandatory_attributes" | s</name> | |||
title="REQUIRED Attributes - List and Definition References"> | <t> | |||
<t> | The list of <bcp14>REQUIRED</bcp14> attributes appears in <xref target="req | |||
The list of REQUIRED attributes appears in <xref target="req_attr_table"/>. | _attr_table" format="default"/>. | |||
The meaning of the columns of the table are: | The meaning of the columns of the table are: | |||
<list style='symbols'> | </t> | |||
<t>Name: The name of the attribute.</t> | <dl spacing="normal"> | |||
<t>Id: The number assigned to the attribute. In | <dt>Name:</dt><dd>The name of the attribute.</dd> | |||
the event of conflicts between the assigned number and <xref | <dt>Id:</dt><dd>The number assigned to the attribute. In | |||
target="RFC5662"/>, the latter is | the event of conflicts between the assigned number and <xref target="RFC | |||
5662" format="default"/>, the latter is | ||||
likely authoritative, but should be resolved with Errata to | likely authoritative, but should be resolved with Errata to | |||
this document and/or | this document and/or | |||
<xref target="RFC5662"/>. See <xref target="errata"/> for the Errata pro | <xref target="RFC5662" format="default"/>. See <xref target="errata" for | |||
cess. | mat="default"/> for the Errata process.</dd> | |||
<dt>Data Type:</dt><dd>The XDR data type of the attribute.</dd> | ||||
</t> | <dt>Acc:</dt><dd>Access allowed to the attribute. R means | |||
<t>Data Type: The XDR data type of the attribute.</t> | ||||
<t> | ||||
Acc: Access allowed to the attribute. R means | ||||
read-only (GETATTR may retrieve, SETATTR may not | read-only (GETATTR may retrieve, SETATTR may not | |||
set). W means write-only (SETATTR may set, GETATTR | set). W means write-only (SETATTR may set, GETATTR | |||
may not retrieve). R W means read/write (GETATTR | may not retrieve). R W means read/write (GETATTR | |||
may retrieve, SETATTR may set). | may retrieve, SETATTR may set).</dd> | |||
<dt>Defined in:</dt><dd>The section of this specification that describ | ||||
</t> | es the | |||
<t>Defined in: The section of this specification that describes the | attribute.</dd> | |||
attribute.</t> | </dl> | |||
</list> | <table anchor="req_attr_table" align="center"> | |||
</t> | <thead> | |||
<tr> | ||||
<texttable anchor="req_attr_table"> | <th align="left">Name</th> | |||
<ttcol align='left' >Name</ttcol> | <th align="left">Id</th> | |||
<ttcol align='left' >Id</ttcol> | <th align="left">Data Type</th> | |||
<ttcol align='left' >Data Type</ttcol> | <th align="left">Acc</th> | |||
<ttcol align='left' >Acc</ttcol> | <th align="left">Defined in:</th> | |||
<ttcol align='left' >Defined in:</ttcol> | </tr> | |||
</thead> | ||||
<c>supported_attrs</c><c>0</c><c>bitmap4</c><c>R</c> | <tbody> | |||
<c> | <tr> | |||
<xref target="attrdef_supp_attr" /> | <td align="left">supported_attrs</td> | |||
</c> | <td align="left">0</td> | |||
<td align="left">bitmap4</td> | ||||
<c>type</c><c>1</c><c>nfs_ftype4</c><c>R</c> | <td align="left">R</td> | |||
<c> | <td align="left"> | |||
<xref target="attrdef_type" /> | <xref target="attrdef_supp_attr" format="default"/> | |||
</c> | </td> | |||
</tr> | ||||
<c>fh_expire_type</c><c>2</c><c>uint32_t</c><c>R</c> | <tr> | |||
<c> | <td align="left">type</td> | |||
<xref target="attrdef_fh_expire_type" /> | <td align="left">1</td> | |||
</c> | <td align="left">nfs_ftype4</td> | |||
<td align="left">R</td> | ||||
<c>change</c><c>3</c><c>uint64_t</c><c>R</c> | <td align="left"> | |||
<c> | <xref target="attrdef_type" format="default"/> | |||
<xref target="attrdef_change" /> | </td> | |||
</c> | </tr> | |||
<tr> | ||||
<c>size</c><c>4</c><c>uint64_t</c><c>R W</c> | <td align="left">fh_expire_type</td> | |||
<c> | <td align="left">2</td> | |||
<xref target="attrdef_size" /> | <td align="left">uint32_t</td> | |||
</c> | <td align="left">R</td> | |||
<td align="left"> | ||||
<c>link_support</c><c>5</c><c>bool</c><c>R</c> | <xref target="attrdef_fh_expire_type" format="default"/> | |||
<c> | </td> | |||
<xref target="attrdef_link_support" /> | </tr> | |||
</c> | <tr> | |||
<td align="left">change</td> | ||||
<c>symlink_support</c><c>6</c><c>bool</c><c>R</c> | <td align="left">3</td> | |||
<c> | <td align="left">uint64_t</td> | |||
<xref target="attrdef_symlink_support" /> | <td align="left">R</td> | |||
</c> | <td align="left"> | |||
<xref target="attrdef_change" format="default"/> | ||||
<c>named_attr</c><c>7</c><c>bool</c><c>R</c> | </td> | |||
<c> | </tr> | |||
<xref target="attrdef_named_attr" /> | <tr> | |||
</c> | <td align="left">size</td> | |||
<td align="left">4</td> | ||||
<c>fsid</c><c>8</c><c>fsid4</c><c>R</c> | <td align="left">uint64_t</td> | |||
<c> | <td align="left">R W</td> | |||
<xref target="attrdef_fsid" /> | <td align="left"> | |||
</c> | <xref target="attrdef_size" format="default"/> | |||
</td> | ||||
<c>unique_handles</c><c>9</c><c>bool</c><c>R</c> | </tr> | |||
<c> | <tr> | |||
<xref target="attrdef_unique_handles" /> | <td align="left">link_support</td> | |||
</c> | <td align="left">5</td> | |||
<td align="left">bool</td> | ||||
<c>lease_time</c><c>10</c><c>nfs_lease4</c><c>R</c> | <td align="left">R</td> | |||
<c> | <td align="left"> | |||
<xref target="attrdef_lease_time" /> | <xref target="attrdef_link_support" format="default"/> | |||
</c> | </td> | |||
</tr> | ||||
<c>rdattr_error</c><c>11</c><c>enum</c><c>R</c> | <tr> | |||
<c> | <td align="left">symlink_support</td> | |||
<xref target="attrdef_rdattr_error" /> | <td align="left">6</td> | |||
</c> | <td align="left">bool</td> | |||
<td align="left">R</td> | ||||
<c>filehandle</c><c>19</c><c>nfs_fh4</c><c>R</c> | <td align="left"> | |||
<c> | <xref target="attrdef_symlink_support" format="default"/> | |||
<xref target="attrdef_filehandle" /> | </td> | |||
</c> | </tr> | |||
<tr> | ||||
<c>suppattr_exclcreat</c><c>75</c><c>bitmap4</c><c>R</c> | <td align="left">named_attr</td> | |||
<c> | <td align="left">7</td> | |||
<xref target="attrdef_suppattr_exclcreat" /> | <td align="left">bool</td> | |||
</c> | <td align="left">R</td> | |||
<td align="left"> | ||||
</texttable> | <xref target="attrdef_named_attr" format="default"/> | |||
</section> | </td> | |||
<section anchor="recommended_attributes" | </tr> | |||
title="RECOMMENDED Attributes - List and Definition References"> | <tr> | |||
<t> | <td align="left">fsid</td> | |||
The RECOMMENDED attributes are defined in | <td align="left">8</td> | |||
<xref target="rec_attr_tbl"/>. The meanings | <td align="left">fsid4</td> | |||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_fsid" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">unique_handles</td> | ||||
<td align="left">9</td> | ||||
<td align="left">bool</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_unique_handles" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">lease_time</td> | ||||
<td align="left">10</td> | ||||
<td align="left">nfs_lease4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_lease_time" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">rdattr_error</td> | ||||
<td align="left">11</td> | ||||
<td align="left">enum</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_rdattr_error" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">filehandle</td> | ||||
<td align="left">19</td> | ||||
<td align="left">nfs_fh4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_filehandle" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">suppattr_exclcreat</td> | ||||
<td align="left">75</td> | ||||
<td align="left">bitmap4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_suppattr_exclcreat" format="default"/> | ||||
</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
</section> | ||||
<section anchor="recommended_attributes" numbered="true" toc="default"> | ||||
<name><bcp14>RECOMMENDED</bcp14> Attributes - List and Definition Refere | ||||
nces</name> | ||||
<t> | ||||
The <bcp14>RECOMMENDED</bcp14> attributes are defined in | ||||
<xref target="rec_attr_tbl" format="default"/>. The meanings | ||||
of the column headers are the same as | of the column headers are the same as | |||
<xref target="req_attr_table"/>; see <xref | <xref target="req_attr_table" format="default"/>; see <xref target="mandato | |||
target="mandatory_attributes" /> for the meanings. | ry_attributes" format="default"/> for the meanings. | |||
</t> | ||||
<texttable anchor="rec_attr_tbl"> | ||||
<ttcol align='left' >Name</ttcol> | ||||
<ttcol align='left' >Id</ttcol> | ||||
<ttcol align='left' >Data Type</ttcol> | ||||
<ttcol align='left' >Acc</ttcol> | ||||
<ttcol align='left' >Defined in:</ttcol> | ||||
<c>acl</c><c>12</c><c>nfsace4<></c><c>R W</c> | ||||
<c> | ||||
<xref target="attrdef_acl" /> | ||||
</c> | ||||
<c>aclsupport</c><c>13</c><c>uint32_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_aclsupport" /> | ||||
</c> | ||||
<c>archive</c><c>14</c><c>bool</c><c>R W</c> | ||||
<c> | ||||
<xref target="attrdef_archive" /> | ||||
</c> | ||||
<c>cansettime</c><c>15</c><c>bool</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_cansettime" /> | ||||
</c> | ||||
<c>case_insensitive</c><c>16</c><c>bool</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_case_insensitive" /> | ||||
</c> | ||||
<c>case_preserving</c><c>17</c><c>bool</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_case_preserving" /> | ||||
</c> | ||||
<c>change_policy</c><c>60</c><c>chg_policy4</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_change_policy" /> | ||||
</c> | ||||
<c>chown_restricted</c><c>18</c><c>bool</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_chown_restricted" /> | ||||
</c> | ||||
<c>dacl</c><c>58</c><c>nfsacl41</c><c>R W</c> | ||||
<c> | ||||
<xref target="attrdef_dacl" /> | ||||
</c> | ||||
<c>dir_notif_delay</c><c>56</c><c>nfstime4</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_dir_notif_delay" /> | ||||
</c> | ||||
<c>dirent_notif_delay</c><c>57</c><c>nfstime4</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_dirent_notif_delay" /> | ||||
</c> | ||||
<c>fileid</c><c>20</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_fileid" /> | ||||
</c> | ||||
<c>files_avail</c><c>21</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_files_avail" /> | ||||
</c> | ||||
<c>files_free</c><c>22</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_files_free" /> | ||||
</c> | ||||
<c>files_total</c><c>23</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_files_total" /> | ||||
</c> | ||||
<c>fs_charset_cap</c><c>76</c><c>uint32_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_fs_charset_cap" /> | ||||
</c> | ||||
<c>fs_layout_type</c><c>62</c><c>layouttype4<></c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_fs_layout_type" /> | ||||
</c> | ||||
<c>fs_locations</c><c>24</c><c>fs_locations</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_fs_locations" /> | ||||
</c> | ||||
<c>fs_locations_info</c><c>67</c><c>*</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_fs_locations_info" /> | ||||
</c> | ||||
<c>fs_status</c><c>61</c><c>fs4_status</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_fs_status" /> | ||||
</c> | ||||
<c>hidden</c><c>25</c><c>bool</c><c>R W</c> | ||||
<c> | ||||
<xref target="attrdef_hidden" /> | ||||
</c> | ||||
<c>homogeneous</c><c>26</c><c>bool</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_homogeneous" /> | ||||
</c> | ||||
<c>layout_alignment</c><c>66</c><c>uint32_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_layout_alignment" /> | ||||
</c> | ||||
<c>layout_blksize</c><c>65</c><c>uint32_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_layout_blksize" /> | ||||
</c> | ||||
<c>layout_hint</c><c>63</c><c>layouthint4</c><c> W</c> | ||||
<c> | ||||
<xref target="attrdef_layout_hint" /> | ||||
</c> | ||||
<c>layout_type</c><c>64</c><c>layouttype4<></c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_layout_type" /> | ||||
</c> | ||||
<c>maxfilesize</c><c>27</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_maxfilesize" /> | ||||
</c> | ||||
<c>maxlink</c><c>28</c><c>uint32_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_maxlink" /> | ||||
</c> | ||||
<c>maxname</c><c>29</c><c>uint32_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_maxname" /> | ||||
</c> | ||||
<c>maxread</c><c>30</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_maxread" /> | ||||
</c> | ||||
<c>maxwrite</c><c>31</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_maxwrite" /> | ||||
</c> | ||||
<c>mdsthreshold</c><c>68</c><c>mdsthreshold4</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_mdsthreshold" /> | ||||
</c> | ||||
<c>mimetype</c><c>32</c><c>utf8str_cs</c><c>R W</c> | ||||
<c> | ||||
<xref target="attrdef_mimetype" /> | ||||
</c> | ||||
<c>mode</c><c>33</c><c>mode4</c><c>R W</c> | ||||
<c> | ||||
<xref target="attrdef_mode" /> | ||||
</c> | ||||
<c>mode_set_masked</c><c>74</c><c>mode_masked4</c><c> W</c> | ||||
<c> | ||||
<xref target="attrdef_mode_set_masked" /> | ||||
</c> | ||||
<c>mounted_on_fileid</c><c>55</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_mounted_on_fileid" /> | ||||
</c> | ||||
<c>no_trunc</c><c>34</c><c>bool</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_no_trunc" /> | ||||
</c> | ||||
<c>numlinks</c><c>35</c><c>uint32_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_numlinks" /> | ||||
</c> | ||||
<c>owner</c> | ||||
<c>36</c><c>utf8str_mixed</c><c>R W</c> | ||||
<c> | ||||
<xref target="attrdef_owner" /> | ||||
</c> | ||||
<c>owner_group</c> | ||||
<c>37</c><c>utf8str_mixed</c><c>R W</c> | ||||
<c> | ||||
<xref target="attrdef_owner_group" /> | ||||
</c> | ||||
<c>quota_avail_hard</c> | ||||
<c>38</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_quota_avail_hard" /> | ||||
</c> | ||||
<c>quota_avail_soft</c> | ||||
<c>39</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_quota_avail_soft" /> | ||||
</c> | ||||
<c>quota_used</c> | ||||
<c>40</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_quota_used" /> | ||||
</c> | ||||
<c>rawdev</c><c>41</c><c>specdata4</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_rawdev" /> | ||||
</c> | ||||
<c>retentevt_get</c><c>71</c><c>retention_get4</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_retentevt_get" /> | ||||
</c> | ||||
<c>retentevt_set</c><c>72</c><c>retention_set4</c><c> W</c> | ||||
<c> | ||||
<xref target="attrdef_retentevt_set" /> | ||||
</c> | ||||
<c>retention_get</c><c>69</c><c>retention_get4</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_retention_get" /> | ||||
</c> | ||||
<c>retention_hold</c><c>73</c><c>uint64_t</c><c>R W</c> | ||||
<c> | ||||
<xref target="attrdef_retention_hold" /> | ||||
</c> | ||||
<c>retention_set</c><c>70</c><c>retention_set4</c><c> W</c> | ||||
<c> | ||||
<xref target="attrdef_retention_set" /> | ||||
</c> | ||||
<c>sacl</c><c>59</c><c>nfsacl41</c><c>R W</c> | ||||
<c> | ||||
<xref target="attrdef_sacl" /> | ||||
</c> | ||||
<c>space_avail</c><c>42</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_space_avail" /> | ||||
</c> | ||||
<c>space_free</c><c>43</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_space_free" /> | ||||
</c> | ||||
<c>space_total</c><c>44</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_space_total" /> | ||||
</c> | ||||
<c>space_used</c><c>45</c><c>uint64_t</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_space_used" /> | ||||
</c> | ||||
<c>system</c><c>46</c><c>bool</c><c>R W</c> | ||||
<c> | ||||
<xref target="attrdef_system" /> | ||||
</c> | ||||
<c>time_access</c> | ||||
<c>47</c><c>nfstime4</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_time_access" /> | ||||
</c> | ||||
<c>time_access_set</c><c>48</c><c>settime4</c><c> W</c> | ||||
<c> | ||||
<xref target="attrdef_time_access_set" /> | ||||
</c> | ||||
<c>time_backup</c><c>49</c><c>nfstime4</c><c>R W</c> | ||||
<c> | ||||
<xref target="attrdef_time_backup" /> | ||||
</c> | ||||
<c>time_create</c><c>50</c><c>nfstime4</c><c>R W</c> | ||||
<c> | ||||
<xref target="attrdef_time_create" /> | ||||
</c> | ||||
<c>time_delta</c><c>51</c><c>nfstime4</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_time_delta" /> | ||||
</c> | ||||
<c>time_metadata</c><c>52</c><c>nfstime4</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_time_metadata" /> | ||||
</c> | ||||
<c>time_modify</c><c>53</c><c>nfstime4</c><c>R</c> | ||||
<c> | ||||
<xref target="attrdef_time_modify" /> | ||||
</c> | ||||
<c>time_modify_set</c><c>54</c><c>settime4</c><c> W</c> | ||||
<c> | ||||
<xref target="attrdef_time_modify_set" /> | ||||
</c> | ||||
</texttable> | ||||
<t>* fs_locations_info4</t> | ||||
</section> | ||||
<section anchor="attribute_definitions" title="Attribute | ||||
Definitions"> | ||||
<section anchor="required_attr" title="Definitions of REQUIRED Attributes"> | </t> | |||
<table anchor="rec_attr_tbl" align="center"> | ||||
<thead> | ||||
<tr> | ||||
<th align="left">Name</th> | ||||
<th align="left">Id</th> | ||||
<th align="left">Data Type</th> | ||||
<th align="left">Acc</th> | ||||
<th align="left">Defined in:</th> | ||||
</tr> | ||||
</thead> | ||||
<tbody> | ||||
<tr> | ||||
<td align="left">acl</td> | ||||
<td align="left">12</td> | ||||
<td align="left">nfsace4<></td> | ||||
<td align="left">R W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_acl" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">aclsupport</td> | ||||
<td align="left">13</td> | ||||
<td align="left">uint32_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_aclsupport" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">archive</td> | ||||
<td align="left">14</td> | ||||
<td align="left">bool</td> | ||||
<td align="left">R W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_archive" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">cansettime</td> | ||||
<td align="left">15</td> | ||||
<td align="left">bool</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_cansettime" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">case_insensitive</td> | ||||
<td align="left">16</td> | ||||
<td align="left">bool</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_case_insensitive" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">case_preserving</td> | ||||
<td align="left">17</td> | ||||
<td align="left">bool</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_case_preserving" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">change_policy</td> | ||||
<td align="left">60</td> | ||||
<td align="left">chg_policy4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_change_policy" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">chown_restricted</td> | ||||
<td align="left">18</td> | ||||
<td align="left">bool</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_chown_restricted" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">dacl</td> | ||||
<td align="left">58</td> | ||||
<td align="left">nfsacl41</td> | ||||
<td align="left">R W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_dacl" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">dir_notif_delay</td> | ||||
<td align="left">56</td> | ||||
<td align="left">nfstime4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_dir_notif_delay" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">dirent_notif_delay</td> | ||||
<td align="left">57</td> | ||||
<td align="left">nfstime4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_dirent_notif_delay" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">fileid</td> | ||||
<td align="left">20</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_fileid" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">files_avail</td> | ||||
<td align="left">21</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_files_avail" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">files_free</td> | ||||
<td align="left">22</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_files_free" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">files_total</td> | ||||
<td align="left">23</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_files_total" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">fs_charset_cap</td> | ||||
<td align="left">76</td> | ||||
<td align="left">uint32_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_fs_charset_cap" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">fs_layout_type</td> | ||||
<td align="left">62</td> | ||||
<td align="left">layouttype4<></td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_fs_layout_type" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">fs_locations</td> | ||||
<td align="left">24</td> | ||||
<td align="left">fs_locations</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_fs_locations" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">fs_locations_info</td> | ||||
<td align="left">67</td> | ||||
<td align="left">fs_locations_info4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_fs_locations_info" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">fs_status</td> | ||||
<td align="left">61</td> | ||||
<td align="left">fs4_status</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_fs_status" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">hidden</td> | ||||
<td align="left">25</td> | ||||
<td align="left">bool</td> | ||||
<td align="left">R W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_hidden" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">homogeneous</td> | ||||
<td align="left">26</td> | ||||
<td align="left">bool</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_homogeneous" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">layout_alignment</td> | ||||
<td align="left">66</td> | ||||
<td align="left">uint32_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_layout_alignment" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">layout_blksize</td> | ||||
<td align="left">65</td> | ||||
<td align="left">uint32_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_layout_blksize" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">layout_hint</td> | ||||
<td align="left">63</td> | ||||
<td align="left">layouthint4</td> | ||||
<td align="left"> W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_layout_hint" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">layout_type</td> | ||||
<td align="left">64</td> | ||||
<td align="left">layouttype4<></td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_layout_type" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">maxfilesize</td> | ||||
<td align="left">27</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_maxfilesize" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">maxlink</td> | ||||
<td align="left">28</td> | ||||
<td align="left">uint32_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_maxlink" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">maxname</td> | ||||
<td align="left">29</td> | ||||
<td align="left">uint32_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_maxname" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">maxread</td> | ||||
<td align="left">30</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_maxread" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">maxwrite</td> | ||||
<td align="left">31</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_maxwrite" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">mdsthreshold</td> | ||||
<td align="left">68</td> | ||||
<td align="left">mdsthreshold4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_mdsthreshold" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">mimetype</td> | ||||
<td align="left">32</td> | ||||
<td align="left">utf8str_cs</td> | ||||
<td align="left">R W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_mimetype" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">mode</td> | ||||
<td align="left">33</td> | ||||
<td align="left">mode4</td> | ||||
<td align="left">R W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_mode" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">mode_set_masked</td> | ||||
<td align="left">74</td> | ||||
<td align="left">mode_masked4</td> | ||||
<td align="left"> W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_mode_set_masked" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">mounted_on_fileid</td> | ||||
<td align="left">55</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_mounted_on_fileid" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">no_trunc</td> | ||||
<td align="left">34</td> | ||||
<td align="left">bool</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_no_trunc" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">numlinks</td> | ||||
<td align="left">35</td> | ||||
<td align="left">uint32_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_numlinks" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">owner</td> | ||||
<td align="left">36</td> | ||||
<td align="left">utf8str_mixed</td> | ||||
<td align="left">R W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_owner" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">owner_group</td> | ||||
<td align="left">37</td> | ||||
<td align="left">utf8str_mixed</td> | ||||
<td align="left">R W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_owner_group" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">quota_avail_hard</td> | ||||
<td align="left">38</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_quota_avail_hard" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">quota_avail_soft</td> | ||||
<td align="left">39</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_quota_avail_soft" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">quota_used</td> | ||||
<td align="left">40</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_quota_used" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">rawdev</td> | ||||
<td align="left">41</td> | ||||
<td align="left">specdata4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_rawdev" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">retentevt_get</td> | ||||
<td align="left">71</td> | ||||
<td align="left">retention_get4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_retentevt_get" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">retentevt_set</td> | ||||
<td align="left">72</td> | ||||
<td align="left">retention_set4</td> | ||||
<td align="left"> W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_retentevt_set" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">retention_get</td> | ||||
<td align="left">69</td> | ||||
<td align="left">retention_get4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_retention_get" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">retention_hold</td> | ||||
<td align="left">73</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_retention_hold" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">retention_set</td> | ||||
<td align="left">70</td> | ||||
<td align="left">retention_set4</td> | ||||
<td align="left"> W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_retention_set" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">sacl</td> | ||||
<td align="left">59</td> | ||||
<td align="left">nfsacl41</td> | ||||
<td align="left">R W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_sacl" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">space_avail</td> | ||||
<td align="left">42</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_space_avail" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">space_free</td> | ||||
<td align="left">43</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_space_free" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">space_total</td> | ||||
<td align="left">44</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_space_total" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">space_used</td> | ||||
<td align="left">45</td> | ||||
<td align="left">uint64_t</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_space_used" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">system</td> | ||||
<td align="left">46</td> | ||||
<td align="left">bool</td> | ||||
<td align="left">R W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_system" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">time_access</td> | ||||
<td align="left">47</td> | ||||
<td align="left">nfstime4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_time_access" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">time_access_set</td> | ||||
<td align="left">48</td> | ||||
<td align="left">settime4</td> | ||||
<td align="left"> W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_time_access_set" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">time_backup</td> | ||||
<td align="left">49</td> | ||||
<td align="left">nfstime4</td> | ||||
<td align="left">R W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_time_backup" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">time_create</td> | ||||
<td align="left">50</td> | ||||
<td align="left">nfstime4</td> | ||||
<td align="left">R W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_time_create" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">time_delta</td> | ||||
<td align="left">51</td> | ||||
<td align="left">nfstime4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_time_delta" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">time_metadata</td> | ||||
<td align="left">52</td> | ||||
<td align="left">nfstime4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_time_metadata" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">time_modify</td> | ||||
<td align="left">53</td> | ||||
<td align="left">nfstime4</td> | ||||
<td align="left">R</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_time_modify" format="default"/> | ||||
</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">time_modify_set</td> | ||||
<td align="left">54</td> | ||||
<td align="left">settime4</td> | ||||
<td align="left"> W</td> | ||||
<td align="left"> | ||||
<xref target="attrdef_time_modify_set" format="default"/> | ||||
</td> | ||||
</tr> | ||||
</tbody> | ||||
<section toc="exclude" anchor="attrdef_supp_attr" | </table> | |||
title="Attribute 0: supported_attrs"> | </section> | |||
<t> | <section anchor="attribute_definitions" numbered="true" toc="default"> | |||
The bit vector that would retrieve all REQUIRED and | <name>Attribute Definitions</name> | |||
RECOMMENDED attributes that are supported for this object. | <section anchor="required_attr" numbered="true" toc="default"> | |||
<name>Definitions of <bcp14>REQUIRED</bcp14> Attributes</name> | ||||
<section toc="exclude" anchor="attrdef_supp_attr" numbered="true"> | ||||
<name>Attribute 0: supported_attrs</name> | ||||
<t> | ||||
The bit vector that would retrieve all <bcp14>REQUIRED</bcp14> and | ||||
<bcp14>RECOMMENDED</bcp14> attributes that are supported for this object. | ||||
The scope of this attribute applies to all objects with a | The scope of this attribute applies to all objects with a | |||
matching fsid. | matching fsid. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_type" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_type" | <name>Attribute 1: type</name> | |||
title="Attribute 1: type"> | <t> | |||
<t> | ||||
Designates the type of an object in terms of one of a number | Designates the type of an object in terms of one of a number | |||
of special constants: | of special constants: | |||
<list style="symbols"> | ||||
<t> | ||||
NF4REG designates a regular file. | ||||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
NF4REG designates a regular file. | ||||
</li> | ||||
<li> | ||||
NF4DIR designates a directory. | NF4DIR designates a directory. | |||
</t> | </li> | |||
<t> | <li> | |||
NF4BLK designates a block device special file. | NF4BLK designates a block device special file. | |||
</t> | </li> | |||
<t> | <li> | |||
NF4CHR designates a character device special file. | NF4CHR designates a character device special file. | |||
</t> | </li> | |||
<t> | <li> | |||
NF4LNK designates a symbolic link. | NF4LNK designates a symbolic link. | |||
</t> | </li> | |||
<t> | <li> | |||
NF4SOCK designates a named socket special file. | NF4SOCK designates a named socket special file. | |||
</t> | </li> | |||
<t> | <li> | |||
NF4FIFO designates a fifo special file. | NF4FIFO designates a fifo special file. | |||
</t> | </li> | |||
<t> | <li> | |||
NF4ATTRDIR designates a named attribute directory. | NF4ATTRDIR designates a named attribute directory. | |||
</t> | </li> | |||
<t> | <li> | |||
NF4NAMEDATTR designates a named attribute. | NF4NAMEDATTR designates a named attribute. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Within the explanatory text and operation descriptions, the | Within the explanatory text and operation descriptions, the | |||
following phrases will be used with the meanings given below: | following phrases will be used with the meanings given below: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The phrase "is a directory" means that the object's | The phrase "is a directory" means that the object's | |||
type attribute is NF4DIR or NF4ATTRDIR. | type attribute is NF4DIR or NF4ATTRDIR. | |||
</t> | </li> | |||
<t> | <li> | |||
The phrase "is a special file" means that the object's type | The phrase "is a special file" means that the object's type | |||
attribute is NF4BLK, NF4CHR, NF4SOCK, or NF4FIFO. | attribute is NF4BLK, NF4CHR, NF4SOCK, or NF4FIFO. | |||
</t> | </li> | |||
<t> | <li> | |||
The phrases "is an ordinary file" and | The phrases "is an ordinary file" and | |||
"is a regular file" mean that the object's | "is a regular file" mean that the object's | |||
type attribute is NF4REG or NF4NAMEDATTR. | type attribute is NF4REG or NF4NAMEDATTR. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
<section toc="exclude" anchor="attrdef_fh_expire_type" numbered="true" | ||||
</section> | > | |||
<name>Attribute 2: fh_expire_type</name> | ||||
<section toc="exclude" anchor="attrdef_fh_expire_type" | <t> | |||
title="Attribute 2: fh_expire_type"> | ||||
<t> | ||||
Server uses this to specify filehandle expiration behavior | Server uses this to specify filehandle expiration behavior | |||
to the client. See <xref target="Filehandles"/> for additional | to the client. See <xref target="Filehandles" format="default"/> for a dditional | |||
description. | description. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_change" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_change" | <name>Attribute 3: change</name> | |||
title="Attribute 3: change"> | <t> | |||
<t> | ||||
A value created by the server that the client can use to | A value created by the server that the client can use to | |||
determine if file data, directory contents, or attributes of | determine if file data, directory contents, or attributes of | |||
the object have been modified. The server may return the | the object have been modified. The server may return the | |||
object's time_metadata attribute for this attribute's value, | object's time_metadata attribute for this attribute's value, | |||
but only if the file system object cannot be updated more | but only if the file system object cannot be updated more | |||
frequently than the resolution of time_metadata. | frequently than the resolution of time_metadata. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_size" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_size" | <name>Attribute 4: size</name> | |||
title="Attribute 4: size"> | <t> | |||
<t> | ||||
The size of the object in bytes. | The size of the object in bytes. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_link_support" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_link_support" | <name>Attribute 5: link_support</name> | |||
title="Attribute 5: link_support"> | <t> | |||
<t> | ||||
TRUE, if the object's file system supports hard links. | TRUE, if the object's file system supports hard links. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_symlink_support" numbered="true | ||||
<section toc="exclude" anchor="attrdef_symlink_support" | "> | |||
title="Attribute 6: symlink_support"> | <name>Attribute 6: symlink_support</name> | |||
<t> | <t> | |||
TRUE, if the object's file system supports symbolic links. | TRUE, if the object's file system supports symbolic links. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_named_attr" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_named_attr" | <name>Attribute 7: named_attr</name> | |||
title="Attribute 7: named_attr"> | <t> | |||
<t> | ||||
TRUE, if this object has named attributes. In other words, | TRUE, if this object has named attributes. In other words, | |||
object has a non-empty named attribute directory. | object has a non-empty named attribute directory. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_fsid" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_fsid" | <name>Attribute 8: fsid</name> | |||
title="Attribute 8: fsid"> | <t> | |||
<t> | ||||
Unique file system identifier for the file system holding this | Unique file system identifier for the file system holding this | |||
object. The fsid attribute has major and minor components, each of | object. The fsid attribute has major and minor components, each of | |||
which are of data type uint64_t. | which are of data type uint64_t. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_unique_handles" numbered="true" | ||||
<section toc="exclude" anchor="attrdef_unique_handles" | > | |||
title="Attribute 9: unique_handles"> | <name>Attribute 9: unique_handles</name> | |||
<t> | <t> | |||
TRUE, if two distinct filehandles are guaranteed to refer to two | TRUE, if two distinct filehandles are guaranteed to refer to two | |||
different file system objects. | different file system objects. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_lease_time" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_lease_time" | <name>Attribute 10: lease_time</name> | |||
title="Attribute 10: lease_time"> | <t> | |||
<t> | ||||
Duration of the lease at server in seconds. | Duration of the lease at server in seconds. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_rdattr_error" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_rdattr_error" | <name>Attribute 11: rdattr_error</name> | |||
title="Attribute 11: rdattr_error"> | <t> | |||
<t> | ||||
Error returned from an attempt to retrieve attributes during a READDIR operation. | Error returned from an attempt to retrieve attributes during a READDIR operation. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_filehandle" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_filehandle" | <name>Attribute 19: filehandle</name> | |||
title="Attribute 19: filehandle"> | <t> | |||
<t> | ||||
The filehandle of this object (primarily for READDIR requests). | The filehandle of this object (primarily for READDIR requests). | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_suppattr_exclcreat" numbered="t | ||||
<section toc="exclude" anchor="attrdef_suppattr_exclcreat" | rue"> | |||
title="Attribute 75: suppattr_exclcreat"> | <name>Attribute 75: suppattr_exclcreat</name> | |||
<t> | <t> | |||
The bit vector that would set all REQUIRED and | The bit vector that would set all <bcp14>REQUIRED</bcp14> and | |||
RECOMMENDED attributes that are supported by the EXCLUSIVE4_1 | <bcp14>RECOMMENDED</bcp14> attributes that are supported by the EXCLUSIVE | |||
4_1 | ||||
method of file creation via the OPEN operation. | method of file creation via the OPEN operation. | |||
The scope of this attribute applies to all objects with a | The scope of this attribute applies to all objects with a | |||
matching fsid. | matching fsid. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | ||||
</section> | <section anchor="recommended_attr" numbered="true" toc="default"> | |||
<name>Definitions of Uncategorized <bcp14>RECOMMENDED</bcp14> Attribut | ||||
<section anchor="recommended_attr" title="Definitions of Uncategorized RECOMM | es</name> | |||
ENDED Attributes"> | <t> | |||
<t> | The definitions of most of the <bcp14>RECOMMENDED</bcp14> attributes follow | |||
The definitions of most of the RECOMMENDED attributes follow. Collections | . Collections | |||
that share a common category are defined in other sections. | that share a common category are defined in other sections. | |||
</t> | </t> | |||
<section toc="exclude" anchor="attrdef_archive" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_archive" | <name>Attribute 14: archive</name> | |||
title="Attribute 14: archive"> | <t> | |||
<t> | ||||
TRUE, if this file has been archived since the time of last | TRUE, if this file has been archived since the time of last | |||
modification (deprecated in favor of time_backup). | modification (deprecated in favor of time_backup). | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_cansettime" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_cansettime" | <name>Attribute 15: cansettime</name> | |||
title="Attribute 15: cansettime"> | <t> | |||
<t> | ||||
TRUE, if the server is able to change the times for a | TRUE, if the server is able to change the times for a | |||
file system object as specified in a SETATTR operation. | file system object as specified in a SETATTR operation. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_case_insensitive" numbered="tru | ||||
<section toc="exclude" anchor="attrdef_case_insensitive" | e"> | |||
title="Attribute 16: case_insensitive"> | <name>Attribute 16: case_insensitive</name> | |||
<t> | <t> | |||
TRUE, if file name comparisons on this file system are case | TRUE, if file name comparisons on this file system are case | |||
insensitive. | insensitive. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_case_preserving" numbered="true | ||||
<section toc="exclude" anchor="attrdef_case_preserving" | "> | |||
title="Attribute 17: case_preserving"> | <name>Attribute 17: case_preserving</name> | |||
<t> | <t> | |||
TRUE, if file name case on this file system is preserved. | TRUE, if file name case on this file system is preserved. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_change_policy" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_change_policy" | <name>Attribute 60: change_policy</name> | |||
title="Attribute 60: change_policy"> | <t> | |||
<t> | ||||
A value created by the server that the client can use to | A value created by the server that the client can use to | |||
determine if some server policy related to the current | determine if some server policy related to the current | |||
file system has been subject to change. If the value | file system has been subject to change. If the value | |||
remains the same, then the client can be sure that the | remains the same, then the client can be sure that the | |||
values of the attributes related to fs location | values of the attributes related to fs location | |||
and the fss_type field of the fs_status attribute have | and the fss_type field of the fs_status attribute have | |||
not changed. On the other hand, a change in this value does | not changed. On the other hand, a change in this value does | |||
necessarily imply a change in policy. It is up to the client | necessarily imply a change in policy. It is up to the client | |||
to interrogate the server to determine if some policy relevant to | to interrogate the server to determine if some policy relevant to | |||
it has changed. See <xref target="chg_policy4" /> for | it has changed. See <xref target="chg_policy4" format="default"/> for | |||
details. | details. | |||
</t> | </t> | |||
<t> | <t> | |||
This attribute MUST change when the value returned by | This attribute <bcp14>MUST</bcp14> change when the value returned by | |||
the fs_locations or fs_locations_info attribute changes, when | the fs_locations or fs_locations_info attribute changes, when | |||
a file system goes from read-only to writable or vice versa, | a file system goes from read-only to writable or vice versa, | |||
or when the allowable set of security flavors for the file system | or when the allowable set of security flavors for the file system | |||
or any part thereof is changed. | or any part thereof is changed. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_chown_restricted" numbered="tru | ||||
<section toc="exclude" anchor="attrdef_chown_restricted" | e"> | |||
title="Attribute 18: chown_restricted"> | <name>Attribute 18: chown_restricted</name> | |||
<t> | <t> | |||
If TRUE, the server will reject any request to change either | If TRUE, the server will reject any request to change either | |||
the owner or the group associated with a file if the caller | the owner or the group associated with a file if the caller | |||
is not a privileged user (for example, "root" in UNIX | is not a privileged user (for example, "root" in UNIX | |||
operating environments or, in Windows 2000, the "Take | operating environments or, in Windows 2000, the "Take | |||
Ownership" privilege). | Ownership" privilege). | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_fileid" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_fileid" | <name>Attribute 20: fileid</name> | |||
title="Attribute 20: fileid"> | <t> | |||
<t> | ||||
A number uniquely identifying the file within the file system. | A number uniquely identifying the file within the file system. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_files_avail" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_files_avail" | <name>Attribute 21: files_avail</name> | |||
title="Attribute 21: files_avail"> | <t> | |||
<t> | ||||
File slots available to this user on the file system | File slots available to this user on the file system | |||
containing this object -- this should be the smallest | containing this object -- this should be the smallest | |||
relevant limit. | relevant limit. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_files_free" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_files_free" | <name>Attribute 22: files_free</name> | |||
title="Attribute 22: files_free"> | <t> | |||
<t> | ||||
Free file slots on the file system containing this object -- | Free file slots on the file system containing this object -- | |||
this should be the smallest relevant limit. | this should be the smallest relevant limit. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_files_total" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_files_total" | <name>Attribute 23: files_total</name> | |||
title="Attribute 23: files_total"> | <t> | |||
<t> | ||||
Total file slots on the file system containing this object. | Total file slots on the file system containing this object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_fs_charset_cap" numbered="true" | ||||
<section toc="exclude" anchor="attrdef_fs_charset_cap" | > | |||
title="Attribute 76: fs_charset_cap"> | <name>Attribute 76: fs_charset_cap</name> | |||
<t> | <t> | |||
Character set capabilities for this file system. See | Character set capabilities for this file system. See | |||
<xref target="utf8_caps"/>. | <xref target="utf8_caps" format="default"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_fs_locations" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_fs_locations" | <name>Attribute 24: fs_locations</name> | |||
title="Attribute 24: fs_locations"> | <t> | |||
<t> | ||||
Locations where this file system may be found. If the server | Locations where this file system may be found. If the server | |||
returns NFS4ERR_MOVED as an error, this attribute MUST be | returns NFS4ERR_MOVED as an error, this attribute <bcp14>MUST</bcp14> be | |||
supported. | supported. | |||
See <xref target="fs_locations"/> for more details. | See <xref target="fs_locations" format="default"/> for more details. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_fs_locations_info" numbered="tr | ||||
<section toc="exclude" anchor="attrdef_fs_locations_info" | ue"> | |||
title="Attribute 67: fs_locations_info"> | <name>Attribute 67: fs_locations_info</name> | |||
<t> | <t> | |||
Full function file system location. | Full function file system location. | |||
See <xref target="SEC11-fsli-info"/> for more details. | See <xref target="SEC11-fsli-info" format="default"/> for more details. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_fs_status" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_fs_status" | <name>Attribute 61: fs_status</name> | |||
title="Attribute 61: fs_status"> | <t> | |||
<t> | ||||
Generic file system type information. | Generic file system type information. | |||
See <xref target="fs_status"/> for more details. | See <xref target="fs_status" format="default"/> for more details. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_hidden" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_hidden" | <name>Attribute 25: hidden</name> | |||
title="Attribute 25: hidden"> | <t> | |||
<t> | ||||
TRUE, if the file is considered hidden with respect to | TRUE, if the file is considered hidden with respect to | |||
the Windows API. | the Windows API. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_homogeneous" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_homogeneous" | <name>Attribute 26: homogeneous</name> | |||
title="Attribute 26: homogeneous"> | <t> | |||
<t> | ||||
TRUE, if this object's file system is homogeneous; i.e., all | TRUE, if this object's file system is homogeneous; i.e., all | |||
objects in the file system (all objects on the server with the | objects in the file system (all objects on the server with the | |||
same fsid) have common values for all per-file-system attributes. | same fsid) have common values for all per-file-system attributes. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_maxfilesize" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_maxfilesize" | <name>Attribute 27: maxfilesize</name> | |||
title="Attribute 27: maxfilesize"> | <t> | |||
<t> | ||||
Maximum supported file size for the file system of this object. | Maximum supported file size for the file system of this object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_maxlink" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_maxlink" | <name>Attribute 28: maxlink</name> | |||
title="Attribute 28: maxlink"> | <t> | |||
<t> | ||||
Maximum number of links for this object. | Maximum number of links for this object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_maxname" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_maxname" | <name>Attribute 29: maxname</name> | |||
title="Attribute 29: maxname"> | <t> | |||
<t> | ||||
Maximum file name size supported for this object. | Maximum file name size supported for this object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_maxread" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_maxread" | <name>Attribute 30: maxread</name> | |||
title="Attribute 30: maxread"> | <t> | |||
<t> | ||||
Maximum amount of data the READ operation will return for this object. | Maximum amount of data the READ operation will return for this object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_maxwrite" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_maxwrite" | <name>Attribute 31: maxwrite</name> | |||
title="Attribute 31: maxwrite"> | <t> | |||
<t> | ||||
Maximum amount of data the WRITE operation will accept for this object. | Maximum amount of data the WRITE operation will accept for this object. | |||
This | This | |||
attribute SHOULD be supported if the file is writable. Lack | attribute <bcp14>SHOULD</bcp14> be supported if the file is writable. La ck | |||
of this attribute can lead to the client either wasting | of this attribute can lead to the client either wasting | |||
bandwidth or not receiving the best performance. | bandwidth or not receiving the best performance. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_mimetype" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_mimetype" | <name>Attribute 32: mimetype</name> | |||
title="Attribute 32: mimetype"> | <t> | |||
<t> | ||||
MIME body type/subtype of this object. | MIME body type/subtype of this object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_mounted_on_fileid" numbered="tr | ||||
<section toc="exclude" anchor="attrdef_mounted_on_fileid" | ue"> | |||
title="Attribute 55: mounted_on_fileid"> | <name>Attribute 55: mounted_on_fileid</name> | |||
<t> | <t> | |||
Like fileid, but if the target filehandle is the root of a | Like fileid, but if the target filehandle is the root of a | |||
file system, this attribute represents the fileid of the | file system, this attribute represents the fileid of the | |||
underlying directory. | underlying directory. | |||
</t> | </t> | |||
<t> | <t> | |||
UNIX-based operating environments connect a file system into | UNIX-based operating environments connect a file system into | |||
the namespace by connecting (mounting) the file system onto | the namespace by connecting (mounting) the file system onto | |||
the existing file object (the mount point, usually a | the existing file object (the mount point, usually a | |||
directory) of an existing file system. When the mount point's | directory) of an existing file system. When the mount point's | |||
parent directory is read via an API like readdir(), the return | parent directory is read via an API like readdir(), the return | |||
results are directory entries, each with a component name and | results are directory entries, each with a component name and | |||
a fileid. The fileid of the mount point's directory entry will | a fileid. The fileid of the mount point's directory entry will | |||
be different from the fileid that the stat() system call | be different from the fileid that the stat() system call | |||
returns. The stat() system call is returning the fileid of the | returns. The stat() system call is returning the fileid of the | |||
root of the mounted file system, whereas readdir() is | root of the mounted file system, whereas readdir() is | |||
returning the fileid that stat() would have returned before any | returning the fileid that stat() would have returned before any | |||
file systems were mounted on the mount point. | file systems were mounted on the mount point. | |||
</t> | </t> | |||
<t> | <t> | |||
Unlike NFSv3, NFSv4.1 allows a client's LOOKUP | Unlike NFSv3, NFSv4.1 allows a client's LOOKUP | |||
request to cross other file systems. The client detects the | request to cross other file systems. The client detects the | |||
file system crossing whenever the filehandle argument of | file system crossing whenever the filehandle argument of | |||
LOOKUP has an fsid attribute different from that of the | LOOKUP has an fsid attribute different from that of the | |||
filehandle returned by LOOKUP. A UNIX-based client will | filehandle returned by LOOKUP. A UNIX-based client will | |||
consider this a "mount point crossing". UNIX has a legacy | consider this a "mount point crossing". UNIX has a legacy | |||
scheme for allowing a process to determine its current working | scheme for allowing a process to determine its current working | |||
directory. This relies on readdir() of a mount point's parent | directory. This relies on readdir() of a mount point's parent | |||
and stat() of the mount point returning fileids as previously | and stat() of the mount point returning fileids as previously | |||
described. The mounted_on_fileid attribute corresponds to the | described. The mounted_on_fileid attribute corresponds to the | |||
fileid that readdir() would have returned as described | fileid that readdir() would have returned as described | |||
previously. | previously. | |||
</t> | </t> | |||
<t> | <t> | |||
While the NFSv4.1 client could simply fabricate a fileid | While the NFSv4.1 client could simply fabricate a fileid | |||
corresponding to what mounted_on_fileid provides (and if the | corresponding to what mounted_on_fileid provides (and if the | |||
server does not support mounted_on_fileid, the client has no | server does not support mounted_on_fileid, the client has no | |||
choice), there is a risk that the client will generate a | choice), there is a risk that the client will generate a | |||
fileid that conflicts with one that is already assigned to | fileid that conflicts with one that is already assigned to | |||
another object in the file system. Instead, if the server can | another object in the file system. Instead, if the server can | |||
provide the mounted_on_fileid, the potential for client | provide the mounted_on_fileid, the potential for client | |||
operational problems in this area is eliminated. | operational problems in this area is eliminated. | |||
</t> | </t> | |||
<t> | <t> | |||
If the server detects that there is no mounted point at the | If the server detects that there is no mounted point at the | |||
target file object, then the value for mounted_on_fileid that | target file object, then the value for mounted_on_fileid that | |||
it returns is the same as that of the fileid attribute. | it returns is the same as that of the fileid attribute. | |||
</t> | </t> | |||
<t> | <t> | |||
The mounted_on_fileid attribute is RECOMMENDED, so the server | The mounted_on_fileid attribute is <bcp14>RECOMMENDED</bcp14>, so the ser | |||
SHOULD provide it if possible, and for a UNIX-based server, | ver | |||
<bcp14>SHOULD</bcp14> provide it if possible, and for a UNIX-based server | ||||
, | ||||
this is straightforward. Usually, mounted_on_fileid will be | this is straightforward. Usually, mounted_on_fileid will be | |||
requested during a READDIR operation, in which case it is | requested during a READDIR operation, in which case it is | |||
trivial (at least for UNIX-based servers) to return | trivial (at least for UNIX-based servers) to return | |||
mounted_on_fileid since it is equal to the fileid of a | mounted_on_fileid since it is equal to the fileid of a | |||
directory entry returned by readdir(). If mounted_on_fileid | directory entry returned by readdir(). If mounted_on_fileid | |||
is requested in a GETATTR operation, the server should obey an | is requested in a GETATTR operation, the server should obey an | |||
invariant that has it returning a value that is equal to the | invariant that has it returning a value that is equal to the | |||
file object's entry in the object's parent directory, | file object's entry in the object's parent directory, | |||
i.e., what readdir() would have returned. Some operating | i.e., what readdir() would have returned. Some operating | |||
environments allow a series of two or more file systems to be | environments allow a series of two or more file systems to be | |||
mounted onto a single mount point. In this case, for the | mounted onto a single mount point. In this case, for the | |||
server to obey the aforementioned invariant, it will need to | server to obey the aforementioned invariant, it will need to | |||
find the base mount point, and not the intermediate mount | find the base mount point, and not the intermediate mount | |||
points. | points. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_no_trunc" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_no_trunc" | <name>Attribute 34: no_trunc</name> | |||
title="Attribute 34: no_trunc"> | <t> | |||
<t> | ||||
If this attribute is TRUE, then if the client uses a file | If this attribute is TRUE, then if the client uses a file | |||
name longer than name_max, an error will be | name longer than name_max, an error will be | |||
returned instead of the name being truncated. | returned instead of the name being truncated. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_numlinks" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_numlinks" | <name>Attribute 35: numlinks</name> | |||
title="Attribute 35: numlinks"> | <t> | |||
<t> | ||||
Number of hard links to this object. | Number of hard links to this object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_owner" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_owner" | <name>Attribute 36: owner</name> | |||
title="Attribute 36: owner"> | <t> | |||
<t> | ||||
The string name of the owner of this object. | The string name of the owner of this object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_owner_group" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_owner_group" | <name>Attribute 37: owner_group</name> | |||
title="Attribute 37: owner_group"> | <t> | |||
<t> | ||||
The string name of the group ownership of this object. | The string name of the group ownership of this object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_quota_avail_hard" numbered="tru | ||||
<section toc="exclude" anchor="attrdef_quota_avail_hard" | e"> | |||
title="Attribute 38: quota_avail_hard"> | <name>Attribute 38: quota_avail_hard</name> | |||
<t anchor="quota_avail_hard"> | <t anchor="quota_avail_hard"> | |||
The value in bytes that represents the amount of additional | The value in bytes that represents the amount of additional | |||
disk space beyond the current allocation that can be allocated | disk space beyond the current allocation that can be allocated | |||
to this file or directory before further allocations will be | to this file or directory before further allocations will be | |||
refused. It is understood that this space may be consumed by | refused. It is understood that this space may be consumed by | |||
allocations to other files or directories. | allocations to other files or directories. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_quota_avail_soft" numbered="tru | ||||
<section toc="exclude" anchor="attrdef_quota_avail_soft" | e"> | |||
title="Attribute 39: quota_avail_soft"> | <name>Attribute 39: quota_avail_soft</name> | |||
<t anchor="quota_avail_soft"> | <t anchor="quota_avail_soft"> | |||
The value in bytes that represents the amount of additional | The value in bytes that represents the amount of additional | |||
disk space that can be allocated to this file or directory | disk space that can be allocated to this file or directory | |||
before the user may reasonably be warned. It is understood | before the user may reasonably be warned. It is understood | |||
that this space may be consumed by allocations to other files | that this space may be consumed by allocations to other files | |||
or directories though there is a rule as to which other files | or directories though there is a rule as to which other files | |||
or directories. | or directories. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_quota_used" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_quota_used" | <name>Attribute 40: quota_used</name> | |||
title="Attribute 40: quota_used"> | <t anchor="quota_used"> | |||
<t anchor="quota_used"> | ||||
The value in bytes that represents the amount of disk | The value in bytes that represents the amount of disk | |||
space used by this file or directory and possibly a | space used by this file or directory and possibly a | |||
number of other similar files or directories, where the | number of other similar files or directories, where the | |||
set of "similar" meets at least the criterion that | set of "similar" meets at least the criterion that | |||
allocating space to any file or directory in the set | allocating space to any file or directory in the set | |||
will reduce the "quota_avail_hard" of every other file | will reduce the "quota_avail_hard" of every other file | |||
or directory in the set. | or directory in the set. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
Note that there may be a number of distinct but | Note that there may be a number of distinct but | |||
overlapping sets of files or directories for which a | overlapping sets of files or directories for which a | |||
quota_used value is maintained, e.g., "all files with a | quota_used value is maintained, e.g., "all files with a | |||
given owner", "all files with a given group owner", etc. | given owner", "all files with a given group owner", etc. | |||
The server is at liberty to choose any of those sets when | The server is at liberty to choose any of those sets when | |||
providing the content of the quota_used attribute, but | providing the content of the quota_used attribute, but | |||
should do so in a repeatable way. The rule may be | should do so in a repeatable way. The rule may be | |||
configured per file system or may be "choose the set with | configured per file system or may be "choose the set with | |||
the smallest quota". | the smallest quota". | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_rawdev" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_rawdev" | <name>Attribute 41: rawdev</name> | |||
title="Attribute 41: rawdev"> | <t> | |||
<t> | ||||
Raw device number of file of type NF4BLK or NF4CHR. The device | Raw device number of file of type NF4BLK or NF4CHR. The device | |||
number is split into major and minor numbers. | number is split into major and minor numbers. | |||
If the file's type attribute is not NF4BLK or NF4CHR, | If the file's type attribute is not NF4BLK or NF4CHR, | |||
the value returned SHOULD NOT be considered useful. | the value returned <bcp14>SHOULD NOT</bcp14> be considered useful. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_space_avail" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_space_avail" | <name>Attribute 42: space_avail</name> | |||
title="Attribute 42: space_avail"> | <t> | |||
<t> | ||||
Disk space in bytes available to this user on the file system | Disk space in bytes available to this user on the file system | |||
containing this object -- this should be the smallest | containing this object -- this should be the smallest | |||
relevant limit. | relevant limit. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_space_free" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_space_free" | <name>Attribute 43: space_free</name> | |||
title="Attribute 43: space_free"> | <t> | |||
<t> | ||||
Free disk space in bytes on the file system containing this | Free disk space in bytes on the file system containing this | |||
object -- this should be the smallest relevant limit. | object -- this should be the smallest relevant limit. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_space_total" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_space_total" | <name>Attribute 44: space_total</name> | |||
title="Attribute 44: space_total"> | <t> | |||
<t> | ||||
Total disk space in bytes on the file system containing this object. | Total disk space in bytes on the file system containing this object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_space_used" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_space_used" | <name>Attribute 45: space_used</name> | |||
title="Attribute 45: space_used"> | <t> | |||
<t> | ||||
Number of file system bytes allocated to this object. | Number of file system bytes allocated to this object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_system" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_system" | <name>Attribute 46: system</name> | |||
title="Attribute 46: system"> | <t> | |||
<t> | ||||
This attribute is TRUE if this file is a "system" file with | This attribute is TRUE if this file is a "system" file with | |||
respect to the Windows operating environment. | respect to the Windows operating environment. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_time_access" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_time_access" | <name>Attribute 47: time_access</name> | |||
title="Attribute 47: time_access"> | <t> | |||
<t> | ||||
The time_access attribute represents the time of last access to | The time_access attribute represents the time of last access to | |||
the object by a READ operation sent to the server. The notion | the object by a READ operation sent to the server. The notion | |||
of what is an "access" depends on the server's operating environment | of what is an "access" depends on the server's operating environment | |||
and/or the server's file system semantics. For example, for | and/or the server's file system semantics. For example, for | |||
servers obeying Portable Operating System Interface (POSIX) semantics, ti me_access would be updated only | servers obeying Portable Operating System Interface (POSIX) semantics, ti me_access would be updated only | |||
by the READ and READDIR operations and not any of the operations | by the READ and READDIR operations and not any of the operations | |||
that modify the content of the object <xref target="read_atime"/>, | that modify the content of the object <xref target="read_atime" format="d | |||
<xref target="readdir_atime"/>, <xref target="write_atime"/>. Of | efault"/>, | |||
<xref target="readdir_atime" format="default"/>, <xref target="write_atim | ||||
e" format="default"/>. Of | ||||
course, setting the corresponding time_access_set attribute is | course, setting the corresponding time_access_set attribute is | |||
another way to modify the time_access attribute. | another way to modify the time_access attribute. | |||
</t> | </t> | |||
<t> | <t> | |||
Whenever the file object resides on a writable file system, | Whenever the file object resides on a writable file system, | |||
the server should make its best efforts to record time_access into | the server should make its best efforts to record time_access into | |||
stable storage. However, to mitigate the performance effects | stable storage. However, to mitigate the performance effects | |||
of doing so, and most especially whenever the server is | of doing so, and most especially whenever the server is | |||
satisfying the read of the object's content from its cache, | satisfying the read of the object's content from its cache, | |||
the server MAY cache access time updates and lazily write them | the server <bcp14>MAY</bcp14> cache access time updates and lazily write them | |||
to stable storage. It is also acceptable to give | to stable storage. It is also acceptable to give | |||
administrators of the server the option to disable time_access | administrators of the server the option to disable time_access | |||
updates. | updates. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_time_access_set" numbered="true | ||||
<section toc="exclude" anchor="attrdef_time_access_set" | "> | |||
title="Attribute 48: time_access_set"> | <name>Attribute 48: time_access_set</name> | |||
<t> | <t> | |||
Sets the time of last access to the object. SETATTR use only. | Sets the time of last access to the object. SETATTR use only. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_time_backup" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_time_backup" | <name>Attribute 49: time_backup</name> | |||
title="Attribute 49: time_backup"> | <t> | |||
<t> | ||||
The time of last backup of the object. | The time of last backup of the object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_time_create" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_time_create" | <name>Attribute 50: time_create</name> | |||
title="Attribute 50: time_create"> | <t> | |||
<t> | ||||
The time of creation of the object. This attribute does not | The time of creation of the object. This attribute does not | |||
have any relation to the traditional UNIX file attribute | have any relation to the traditional UNIX file attribute | |||
"ctime" or "change time". | "ctime" or "change time". | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_time_delta" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_time_delta" | <name>Attribute 51: time_delta</name> | |||
title="Attribute 51: time_delta"> | <t> | |||
<t> | ||||
Smallest useful server time granularity. | Smallest useful server time granularity. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_time_metadata" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_time_metadata" | <name>Attribute 52: time_metadata</name> | |||
title="Attribute 52: time_metadata"> | <t> | |||
<t> | ||||
The time of last metadata modification of the object. | The time of last metadata modification of the object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_time_modify" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_time_modify" | <name>Attribute 53: time_modify</name> | |||
title="Attribute 53: time_modify"> | <t> | |||
<t> | ||||
The time of last modification to the object. | The time of last modification to the object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_time_modify_set" numbered="true | ||||
<section toc="exclude" anchor="attrdef_time_modify_set" | "> | |||
title="Attribute 54: time_modify_set"> | <name>Attribute 54: time_modify_set</name> | |||
<t> | <t> | |||
Sets the time of last modification to the object. SETATTR use only. | Sets the time of last modification to the object. SETATTR use only. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | ||||
</section> | </section> | |||
<section anchor="owner_owner_group" numbered="true" toc="default"> | ||||
</section> | <name>Interpreting owner and owner_group</name> | |||
<t> | ||||
<section anchor="owner_owner_group" | The <bcp14>RECOMMENDED</bcp14> attributes "owner" and "owner_group" (and a | |||
title="Interpreting owner and owner_group"> | lso | |||
<t> | ||||
The RECOMMENDED attributes "owner" and "owner_group" (and also | ||||
users and groups within the "acl" attribute) are represented in | users and groups within the "acl" attribute) are represented in | |||
terms of a UTF-8 string. To avoid a representation that is tied | terms of a UTF-8 string. To avoid a representation that is tied | |||
to a particular underlying implementation at the client or | to a particular underlying implementation at the client or | |||
server, the use of the UTF-8 string has been chosen. Note that | server, the use of the UTF-8 string has been chosen. Note that | |||
Section 6.1 of <xref target="RFC2624">RFC 2624</xref> provides | Section <xref target="RFC2624" sectionFormat="bare" section="6.1"/> | |||
of RFC 2624 <xref target="RFC2624" format="default"/> provides | ||||
additional rationale. It is expected that the client and server | additional rationale. It is expected that the client and server | |||
will have their own local representation of owner and | will have their own local representation of owner and | |||
owner_group that is used for local storage or presentation to | owner_group that is used for local storage or presentation to | |||
the end user. Therefore, it is expected that when these | the end user. Therefore, it is expected that when these | |||
attributes are transferred between the client and server, | attributes are transferred between the client and server, | |||
the local representation is translated to a syntax of the form | the local representation is translated to a syntax of the form | |||
"user@dns_domain". This will allow for a client and server that | "user@dns_domain". This will allow for a client and server that | |||
do not use the same local representation the ability to | do not use the same local representation the ability to | |||
translate to a common syntax that can be interpreted by both. | translate to a common syntax that can be interpreted by both. | |||
</t> | </t> | |||
<t> | <t> | |||
Similarly, security principals may be represented in different | Similarly, security principals may be represented in different | |||
ways by different security mechanisms. Servers normally | ways by different security mechanisms. Servers normally | |||
translate these representations into a common format, | translate these representations into a common format, | |||
generally that used by local storage, to serve as a means of | generally that used by local storage, to serve as a means of | |||
identifying the users corresponding to these security | identifying the users corresponding to these security | |||
principals. When these local identifiers are translated to | principals. When these local identifiers are translated to | |||
the form of the owner attribute, associated with files created | the form of the owner attribute, associated with files created | |||
by such principals, they identify, in a common format, the | by such principals, they identify, in a common format, the | |||
users associated with each corresponding set of security | users associated with each corresponding set of security | |||
principals. | principals. | |||
</t> | </t> | |||
<t> | <t> | |||
The translation used to interpret owner and group strings is | The translation used to interpret owner and group strings is | |||
not specified as part of the protocol. This allows various | not specified as part of the protocol. This allows various | |||
solutions to be employed. For example, a local translation | solutions to be employed. For example, a local translation | |||
table may be consulted that maps a numeric identifier to the | table may be consulted that maps a numeric identifier to the | |||
user@dns_domain syntax. A name service may also be used to | user@dns_domain syntax. A name service may also be used to | |||
accomplish the translation. A server may provide a more | accomplish the translation. A server may provide a more | |||
general service, not limited by any particular translation | general service, not limited by any particular translation | |||
(which would only translate a limited set of possible strings) | (which would only translate a limited set of possible strings) | |||
by storing the owner and owner_group attributes in local | by storing the owner and owner_group attributes in local | |||
storage without any translation or it may augment a | storage without any translation or it may augment a | |||
translation method by storing the entire string for attributes | translation method by storing the entire string for attributes | |||
for which no translation is available while using the local | for which no translation is available while using the local | |||
representation for those cases in which a translation is | representation for those cases in which a translation is | |||
available. | available. | |||
</t> | </t> | |||
<t> | <t> | |||
Servers that do not provide support for all possible values of | Servers that do not provide support for all possible values of | |||
the owner and owner_group attributes SHOULD return an error | the owner and owner_group attributes <bcp14>SHOULD</bcp14> return an error | |||
(NFS4ERR_BADOWNER) when a string is presented that has no | (NFS4ERR_BADOWNER) when a string is presented that has no | |||
translation, as the value to be set for a SETATTR of the | translation, as the value to be set for a SETATTR of the | |||
owner, owner_group, or acl attributes. When a server does | owner, owner_group, or acl attributes. When a server does | |||
accept an owner or owner_group value as valid on a SETATTR | accept an owner or owner_group value as valid on a SETATTR | |||
(and similarly for the owner and group strings in an acl), it | (and similarly for the owner and group strings in an acl), it | |||
is promising to return that same string when a corresponding | is promising to return that same string when a corresponding | |||
GETATTR is done. Configuration changes (including | GETATTR is done. Configuration changes (including | |||
changes from the mapping of the string to the local representation) | changes from the mapping of the string to the local representation) | |||
and ill-constructed | and ill-constructed | |||
name translations (those that contain aliasing) may make that | name translations (those that contain aliasing) may make that | |||
promise impossible to honor. Servers should make appropriate | promise impossible to honor. Servers should make appropriate | |||
efforts to avoid a situation in which these attributes have | efforts to avoid a situation in which these attributes have | |||
their values changed when no real change to ownership has | their values changed when no real change to ownership has | |||
occurred. | occurred. | |||
</t> | </t> | |||
<t> | <t> | |||
The "dns_domain" portion of the owner string is meant to be a | The "dns_domain" portion of the owner string is meant to be a | |||
DNS domain name, for example, user@example.org. Servers should | DNS domain name, for example, user@example.org. Servers should | |||
accept as valid a set of users for at least one domain. A | accept as valid a set of users for at least one domain. A | |||
server may treat other domains as having no valid | server may treat other domains as having no valid | |||
translations. A more general service is provided when a | translations. A more general service is provided when a | |||
server is capable of accepting users for multiple domains, or | server is capable of accepting users for multiple domains, or | |||
for all domains, subject to security constraints. | for all domains, subject to security constraints. | |||
</t> | </t> | |||
<t> | <t> | |||
In the case where there is no translation available to the | In the case where there is no translation available to the | |||
client or server, the attribute value will be constructed | client or server, the attribute value will be constructed | |||
without the "@". Therefore, the absence of the @ from the | without the "@". Therefore, the absence of the @ from the | |||
owner or owner_group attribute signifies that no translation | owner or owner_group attribute signifies that no translation | |||
was available at the sender and that the receiver of the | was available at the sender and that the receiver of the | |||
attribute should not use that string as a basis for | attribute should not use that string as a basis for | |||
translation into its own internal format. Even though the | translation into its own internal format. Even though the | |||
attribute value cannot be translated, it may still be useful. | attribute value cannot be translated, it may still be useful. | |||
In the case of a client, the attribute string may be used for | In the case of a client, the attribute string may be used for | |||
local display of ownership. | local display of ownership. | |||
</t> | </t> | |||
<t> | <t> | |||
To provide a greater degree of compatibility with NFSv3, | To provide a greater degree of compatibility with NFSv3, | |||
which identified users and groups by 32-bit unsigned user | which identified users and groups by 32-bit unsigned user | |||
identifiers and group identifiers, owner and group strings that | identifiers and group identifiers, owner and group strings that | |||
consist of decimal numeric values with no leading zeros can be | consist of decimal numeric values with no leading zeros can be | |||
given a special interpretation by clients and servers that | given a special interpretation by clients and servers that | |||
choose to provide such support. The receiver may treat such a | choose to provide such support. The receiver may treat such a | |||
user or group string as representing the same user as would be | user or group string as representing the same user as would be | |||
represented by an NFSv3 uid or gid having the corresponding | represented by an NFSv3 uid or gid having the corresponding | |||
numeric value. A server is not obligated to accept such a | numeric value. A server is not obligated to accept such a | |||
string, but may return an NFS4ERR_BADOWNER instead. To avoid | string, but may return an NFS4ERR_BADOWNER instead. To avoid | |||
this mechanism being used to subvert user and group translation, | this mechanism being used to subvert user and group translation, | |||
so that a client might pass all of the owners and groups in | so that a client might pass all of the owners and groups in | |||
numeric form, a server SHOULD return an NFS4ERR_BADOWNER error | numeric form, a server <bcp14>SHOULD</bcp14> return an NFS4ERR_BADOWNER er ror | |||
when there is a valid translation for the user or owner | when there is a valid translation for the user or owner | |||
designated in this way. In that case, the client must use the | designated in this way. In that case, the client must use the | |||
appropriate name@domain string and not the special form for compatibility. | appropriate name@domain string and not the special form for compatibility. | |||
</t> | </t> | |||
<t> | <t> | |||
The owner string "nobody" may be used to designate an | The owner string "nobody" may be used to designate an | |||
anonymous user, which will be associated with a file created | anonymous user, which will be associated with a file created | |||
by a security principal that cannot be mapped through normal | by a security principal that cannot be mapped through normal | |||
means to the owner attribute. Users and implementations | means to the owner attribute. Users and implementations | |||
of NFSv4.1 SHOULD NOT use "nobody" to designate a real user whose access i | of NFSv4.1 <bcp14>SHOULD NOT</bcp14> use "nobody" to designate a real user | |||
s not anonymous. | whose access is not anonymous. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="character_case_attributes" numbered="true" toc="default"> | ||||
<section anchor="character_case_attributes" | <name>Character Case Attributes</name> | |||
title="Character Case Attributes"> | <t> | |||
<t> | ||||
With respect to the case_insensitive and case_preserving | With respect to the case_insensitive and case_preserving | |||
attributes, each UCS-4 character (which UTF-8 encodes) can be | attributes, each UCS-4 character (which UTF-8 encodes) can be | |||
mapped according to Appendix B.2 of | mapped according to Appendix | |||
<xref target="RFC3454">RFC 3454</xref>. | <xref target="RFC3454" sectionFormat="bare" section="B.2"/> | |||
of RFC 3454 <xref target="RFC3454" format="default"/>. | ||||
For general character handling and internationalization issues, | For general character handling and internationalization issues, | |||
see <xref target="internationalization"/>. | see <xref target="internationalization" format="default"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="dir_not_attrs" numbered="true" toc="default"> | ||||
<section title="Directory Notification Attributes" anchor="dir_not_attrs"> | <name>Directory Notification Attributes</name> | |||
<t> | <t> | |||
As described in <xref target="OP_GET_DIR_DELEGATION" />, the | As described in <xref target="OP_GET_DIR_DELEGATION" format="default"/>, t | |||
he | ||||
client can request a minimum delay for notifications of changes | client can request a minimum delay for notifications of changes | |||
to attributes, but the server is free to ignore what the client | to attributes, but the server is free to ignore what the client | |||
requests. The client can determine in advance what notification | requests. The client can determine in advance what notification | |||
delays the server will accept by sending a GETATTR operation for either or | delays the server will accept by sending a GETATTR operation for either or | |||
both of two directory notification attributes. When the client | both of two directory notification attributes. When the client | |||
calls the GET_DIR_DELEGATION operation and asks for attribute | calls the GET_DIR_DELEGATION operation and asks for attribute | |||
change notifications, it should request notification delays that | change notifications, it should request notification delays that | |||
are no less than the values in the server-provided attributes. | are no less than the values in the server-provided attributes. | |||
</t> | </t> | |||
<section toc="exclude" anchor="attrdef_dir_notif_delay" | <section toc="exclude" anchor="attrdef_dir_notif_delay" numbered="true"> | |||
title="Attribute 56: dir_notif_delay"> | <name>Attribute 56: dir_notif_delay</name> | |||
<t> | <t> | |||
The dir_notif_delay attribute is the minimum number of seconds | The dir_notif_delay attribute is the minimum number of seconds | |||
the server will delay before notifying the client of a change | the server will delay before notifying the client of a change | |||
to the directory's attributes. | to the directory's attributes. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_dirent_notif_delay" numbered="tru | ||||
<section toc="exclude" anchor="attrdef_dirent_notif_delay" | e"> | |||
title="Attribute 57: dirent_notif_delay"> | <name>Attribute 57: dirent_notif_delay</name> | |||
<t> | <t> | |||
The dirent_notif_delay attribute is the minimum number of seconds | The dirent_notif_delay attribute is the minimum number of seconds | |||
the server will delay before notifying the client of a change | the server will delay before notifying the client of a change | |||
to a file object that has an entry in the directory. | to a file object that has an entry in the directory. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | ||||
</section> | <section anchor="pnfs_attr_full" numbered="true" toc="default"> | |||
<name>pNFS Attribute Definitions</name> | ||||
<section anchor="pnfs_attr_full" title="pNFS Attribute Definitions"> | <section toc="exclude" anchor="attrdef_fs_layout_type" numbered="true"> | |||
<name>Attribute 62: fs_layout_type</name> | ||||
<section toc="exclude" anchor="attrdef_fs_layout_type" | <t> | |||
title="Attribute 62: fs_layout_type"> | ||||
<t> | ||||
The fs_layout_type attribute (see | The fs_layout_type attribute (see | |||
<xref target="layouttype4"/>) applies to a | <xref target="layouttype4" format="default"/>) applies to a | |||
file system and indicates what layout types are supported by | file system and indicates what layout types are supported by | |||
the file system. When the client encounters a new fsid, the | the file system. When the client encounters a new fsid, the | |||
client SHOULD obtain the value for the fs_layout_type | client <bcp14>SHOULD</bcp14> obtain the value for the fs_layout_type | |||
attribute associated with the new file system. This attribute | attribute associated with the new file system. This attribute | |||
is used by the client to determine if the layout types | is used by the client to determine if the layout types | |||
supported by the server match any of the client's supported | supported by the server match any of the client's supported | |||
layout types. | layout types. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_layout_alignment" numbered="true" | ||||
<section toc="exclude" anchor="attrdef_layout_alignment" | > | |||
title="Attribute 66: layout_alignment"> | <name>Attribute 66: layout_alignment</name> | |||
<t> | <t> | |||
When a client holds layouts on files of a file system, the | When a client holds layouts on files of a file system, the | |||
layout_alignment attribute indicates the preferred alignment | layout_alignment attribute indicates the preferred alignment | |||
for I/O to files on that file system. Where possible, the | for I/O to files on that file system. Where possible, the | |||
client should send READ and WRITE operations with offsets | client should send READ and WRITE operations with offsets | |||
that are whole multiples of the layout_alignment attribute. | that are whole multiples of the layout_alignment attribute. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_layout_blksize" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_layout_blksize" | <name>Attribute 65: layout_blksize</name> | |||
title="Attribute 65: layout_blksize"> | <t> | |||
<t> | ||||
When a client holds layouts on files of a file system, the | When a client holds layouts on files of a file system, the | |||
layout_blksize attribute indicates the preferred block size | layout_blksize attribute indicates the preferred block size | |||
for I/O to files on that file system. Where possible, the | for I/O to files on that file system. Where possible, the | |||
client should send READ operations with a count argument that | client should send READ operations with a count argument that | |||
is a whole multiple of layout_blksize, and WRITE operations | is a whole multiple of layout_blksize, and WRITE operations | |||
with a data argument of size that is a whole multiple of | with a data argument of size that is a whole multiple of | |||
layout_blksize. | layout_blksize. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_layout_hint" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_layout_hint" | <name>Attribute 63: layout_hint</name> | |||
title="Attribute 63: layout_hint"> | <t> | |||
<t> | ||||
The layout_hint attribute (see | The layout_hint attribute (see | |||
<xref target="layouthint4"/>) may be set on | <xref target="layouthint4" format="default"/>) may be set on | |||
newly created files to influence the metadata server's choice | newly created files to influence the metadata server's choice | |||
for the file's layout. If possible, this attribute is one of | for the file's layout. If possible, this attribute is one of | |||
those set in the initial attributes within the OPEN operation. | those set in the initial attributes within the OPEN operation. | |||
The metadata server may choose to ignore this attribute. The | The metadata server may choose to ignore this attribute. The | |||
layout_hint attribute is a subset of the layout structure | layout_hint attribute is a subset of the layout structure | |||
returned by LAYOUTGET. For example, instead of specifying | returned by LAYOUTGET. For example, instead of specifying | |||
particular devices, this would be used to suggest the stripe | particular devices, this would be used to suggest the stripe | |||
width of a file. The server implementation determines which | width of a file. The server implementation determines which | |||
fields within the layout will be used. | fields within the layout will be used. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_layout_type" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_layout_type" | <name>Attribute 64: layout_type</name> | |||
title="Attribute 64: layout_type"> | <t> | |||
<t> | ||||
This attribute lists the layout type(s) available for a file. | This attribute lists the layout type(s) available for a file. | |||
The value returned by the server is for informational purposes | The value returned by the server is for informational purposes | |||
only. The client will use the LAYOUTGET operation to obtain | only. The client will use the LAYOUTGET operation to obtain | |||
the information needed in order to perform I/O, for example, | the information needed in order to perform I/O, for example, | |||
the specific device information for the file and its layout. | the specific device information for the file and its layout. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_mdsthreshold" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_mdsthreshold" | <name>Attribute 68: mdsthreshold</name> | |||
title="Attribute 68: mdsthreshold"> | <t> | |||
<t> | ||||
This attribute is a server-provided hint used to communicate | This attribute is a server-provided hint used to communicate | |||
to the client when it is more efficient to send READ and | to the client when it is more efficient to send READ and | |||
WRITE operations to the metadata server or the data server. | WRITE operations to the metadata server or the data server. | |||
The two types of thresholds described are file size thresholds | The two types of thresholds described are file size thresholds | |||
and I/O size thresholds. If a file's size is smaller than the | and I/O size thresholds. If a file's size is smaller than the | |||
file size threshold, data accesses SHOULD be sent to the | file size threshold, data accesses <bcp14>SHOULD</bcp14> be sent to the | |||
metadata server. If an I/O request has a length | metadata server. If an I/O request has a length | |||
that is below the I/O size threshold, | that is below the I/O size threshold, | |||
the I/O SHOULD be sent to the metadata server. | the I/O <bcp14>SHOULD</bcp14> be sent to the metadata server. | |||
Each threshold type is specified separately for read and | Each threshold type is specified separately for read and | |||
write. | write. | |||
</t> | </t> | |||
<t> | <t> | |||
The server MAY provide both types of thresholds for a file. | The server <bcp14>MAY</bcp14> provide both types of thresholds for a file | |||
If both file size and I/O size are provided, the client SHOULD | . | |||
If both file size and I/O size are provided, the client <bcp14>SHOULD</bc | ||||
p14> | ||||
reach or exceed both thresholds before sending its read or write | reach or exceed both thresholds before sending its read or write | |||
requests to the data server. Alternatively, if only one of | requests to the data server. Alternatively, if only one of | |||
the specified thresholds is reached or exceeded, the I/O requests are | the specified thresholds is reached or exceeded, the I/O requests are | |||
sent to the metadata server. | sent to the metadata server. | |||
</t> | </t> | |||
<t> | <t> | |||
For each threshold type, a value of zero indicates no READ or WRITE | For each threshold type, a value of zero indicates no READ or WRITE | |||
should be sent to the metadata server, while a value of all ones | should be sent to the metadata server, while a value of all ones | |||
indicates that all READs or WRITEs should be sent to the metadata | indicates that all READs or WRITEs should be sent to the metadata | |||
server. | server. | |||
</t> | </t> | |||
<t> | <t> | |||
The attribute is available on a per-filehandle basis. If the | The attribute is available on a per-filehandle basis. If the | |||
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> <!-- "PNFS Attributes" --> | </section> | |||
<section anchor="retention" title="Retention Attributes"> | <section anchor="retention" numbered="true" toc="default"> | |||
<t> | <name>Retention Attributes</name> | |||
<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> | |||
<t> | <t> | |||
When retention is enabled, retention MUST extend to the data of | When retention is enabled, retention <bcp14>MUST</bcp14> extend to the dat | |||
the file, and the name of file. The server MAY extend retention | a of | |||
the file, and the name of file. The server <bcp14>MAY</bcp14> extend reten | ||||
tion | ||||
to any other property of the file, including any subset of | to any other property of the file, including any subset of | |||
REQUIRED, RECOMMENDED, and named attributes, with the | <bcp14>REQUIRED</bcp14>, <bcp14>RECOMMENDED</bcp14>, and named attributes, with the | |||
exceptions noted in this section. | exceptions noted in this section. | |||
</t> | </t> | |||
<t> | <t> | |||
Servers MAY support or not support retention on | Servers <bcp14>MAY</bcp14> support or not support retention on | |||
any file object type. | any file object type. | |||
</t> | </t> | |||
<t> | <t> | |||
The five retention attributes are explained in the next subsections. | The five retention attributes are explained in the next subsections. | |||
</t> | </t> | |||
<section toc="exclude" anchor="attrdef_retention_get" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_retention_get" | <name>Attribute 69: retention_get</name> | |||
title="Attribute 69: retention_get"> | <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 MUST NOT be modified by the SETATTR operation | and <bcp14>MUST NOT</bcp14> be modified by the SETATTR operation | |||
(<xref target="rw_attr"/>). The value of the | (<xref target="rw_attr" format="default"/>). The value of the | |||
attribute consists of: | attribute consists of: | |||
<figure> | </t> | |||
<artwork> | <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>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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 | |||
field rg_begin_time is an array of up to one absolute time | field rg_begin_time is an array of up to one absolute time | |||
value. If the array is zero length, no beginning retention time | value. If the array is zero length, no beginning retention time | |||
has been established, and retention is not enabled. | has been established, and retention is not enabled. | |||
If rg_duration is equal to RET4_DURATION_INFINITE, the file, once | If rg_duration is equal to RET4_DURATION_INFINITE, the file, once | |||
retention is enabled, will be retained for an infinite duration. | retention is enabled, will be retained for an infinite duration. | |||
</t> | </t> | |||
<t> | <t> | |||
If (as soon as) rg_duration is zero, then rg_begin_time will be | If (as soon as) rg_duration is zero, then rg_begin_time will be | |||
of zero length, and again, retention is not (no longer) enabled. | of zero length, and again, retention is not (no longer) enabled. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_retention_set" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_retention_set" | <name>Attribute 70: retention_set</name> | |||
title="Attribute 70: retention_set"> | <t> | |||
<t> | ||||
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 | |||
MUST NOT be retrieved by the GETATTR operation | <bcp14>MUST NOT</bcp14> be retrieved by the GETATTR operation | |||
(<xref target="rw_attr"/>). | (<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: | |||
<figure> | </t> | |||
<artwork> | <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>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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 | |||
duration of the retention can also be provided if the | duration of the retention can also be provided if the | |||
rs_duration array is of length one. The duration is the time in | rs_duration array is of length one. The duration is the time in | |||
seconds from the begin time of retention, and if set to | seconds from the begin time of retention, and if set to | |||
RET4_DURATION_INFINITE, the file is to be retained forever. If | RET4_DURATION_INFINITE, the file is to be retained forever. If | |||
retention is enabled, with no duration specified in either | retention is enabled, with no duration specified in either | |||
this SETATTR or a previous SETATTR, the duration defaults to | this SETATTR or a previous SETATTR, the duration defaults to | |||
zero seconds. The server MAY restrict the enabling of | zero seconds. The server <bcp14>MAY</bcp14> restrict the enabling of | |||
retention or the duration of retention on the basis of the | retention or the duration of retention on the basis of the | |||
ACE4_WRITE_RETENTION ACL permission. The enabling of | ACE4_WRITE_RETENTION ACL permission. The enabling of | |||
retention MUST NOT prevent the enabling of event-based | retention <bcp14>MUST NOT</bcp14> prevent the enabling of event-based | |||
retention or the modification of the retention_hold | retention or the modification of the retention_hold | |||
attribute. | attribute. | |||
</t> | </t> | |||
<t> | <t> | |||
The following rules apply to both the retention_set and | The following rules apply to both the retention_set and | |||
retentevt_set attributes. | retentevt_set attributes. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
As long as retention is not enabled, the client | As long as retention is not enabled, the client | |||
is permitted to decrease the duration. | is permitted to decrease the duration. | |||
</t> | </li> | |||
<t> | <li> | |||
The duration can always be set to an | The duration can always be set to an | |||
equal or higher value, even if retention is | equal or higher value, even if retention is | |||
enabled. Note that once retention is enabled, | enabled. Note that once retention is enabled, | |||
the actual duration (as returned by the | the actual duration (as returned by the | |||
retention_get or retentevt_get attributes; | retention_get or retentevt_get attributes; | |||
see <xref target="attrdef_retention_get"/> | see <xref target="attrdef_retention_get" format="default"/> | |||
or <xref target="attrdef_retentevt_get"/>) | or <xref target="attrdef_retentevt_get" format="default"/>) | |||
is constantly counting down to zero (one unit | is constantly counting down to zero (one unit | |||
per second), unless the duration was set to | per second), unless the duration was set to | |||
RET4_DURATION_INFINITE. Thus, it will not be | RET4_DURATION_INFINITE. Thus, it will not be | |||
possible for the client to precisely extend the | possible for the client to precisely extend the | |||
duration on a file that has retention enabled. | duration on a file that has retention enabled. | |||
</t> | </li> | |||
<t> | <li> | |||
While retention is enabled, attempts to disable | While retention is enabled, attempts to disable | |||
retention or decrease the retention's duration | retention or decrease the retention's duration | |||
MUST fail with the error NFS4ERR_INVAL. | <bcp14>MUST</bcp14> fail with the error NFS4ERR_INVAL. | |||
</t> | ||||
<t> | </li> | |||
<li> | ||||
If the principal attempting to change | If the principal attempting to change | |||
retention_set or retentevt_set does not have | retention_set or retentevt_set does not have | |||
ACE4_WRITE_RETENTION permissions, the attempt | ACE4_WRITE_RETENTION permissions, the attempt | |||
MUST fail with NFS4ERR_ACCESS. | <bcp14>MUST</bcp14> fail with NFS4ERR_ACCESS. | |||
</t> | ||||
</list> | ||||
</t> | ||||
</section> | ||||
<section toc="exclude" anchor="attrdef_retentevt_get" | </li> | |||
title="Attribute 71: retentevt_get"> | </ul> | |||
<t> | </section> | |||
<section toc="exclude" anchor="attrdef_retentevt_get" numbered="true"> | ||||
<name>Attribute 71: retentevt_get</name> | ||||
<t> | ||||
Gets the event-based retention duration, and if enabled, the | Gets the event-based retention duration, and if enabled, the | |||
event-based retention begin time of the file object. This | event-based retention begin time of the file object. This | |||
attribute is like retention_get, but refers to event-based | attribute is like retention_get, but refers to event-based | |||
retention. The event that triggers event-based retention is | retention. The event that triggers event-based retention is | |||
not defined by the NFSv4.1 specification. | not defined by the NFSv4.1 specification. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_retentevt_set" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_retentevt_set" | <name>Attribute 72: retentevt_set</name> | |||
title="Attribute 72: retentevt_set"> | <t> | |||
<t> | ||||
Sets the event-based retention duration, and optionally enables | Sets the event-based retention duration, and optionally enables | |||
event-based retention on the file object. This attribute | event-based retention on the file object. This attribute | |||
corresponds to retentevt_get and is like retention_set, but | corresponds to retentevt_get and is like retention_set, but | |||
refers to event-based retention. When event-based retention | refers to event-based retention. When event-based retention | |||
is set, the file MUST be retained even if non-event-based | is set, the file <bcp14>MUST</bcp14> be retained even if non-event-based | |||
retention has been set, and the duration of non-event-based | retention has been set, and the duration of non-event-based | |||
retention has been reached. Conversely, when non-event-based | retention has been reached. Conversely, when non-event-based | |||
retention has been set, the file MUST be retained even if | retention has been set, the file <bcp14>MUST</bcp14> be retained even if | |||
event-based retention has been set, and the duration of | event-based retention has been set, and the duration of | |||
event-based retention has been reached. The server MAY | event-based retention has been reached. The server <bcp14>MAY</bcp14> | |||
restrict the enabling of event-based retention or the duration | restrict the enabling of event-based retention or the duration | |||
of event-based retention on the basis of the | of event-based retention on the basis of the | |||
ACE4_WRITE_RETENTION ACL permission. The enabling of | ACE4_WRITE_RETENTION ACL permission. The enabling of | |||
event-based retention MUST NOT prevent the enabling of | event-based retention <bcp14>MUST NOT</bcp14> prevent the enabling of | |||
non-event-based retention or the modification of the | non-event-based retention or the modification of the | |||
retention_hold attribute. | retention_hold attribute. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="attrdef_retention_hold" numbered="true"> | ||||
<section toc="exclude" anchor="attrdef_retention_hold" | <name>Attribute 73: retention_hold</name> | |||
title="Attribute 73: retention_hold"> | <t> | |||
<t> | ||||
Gets or sets administrative retention holds, one hold per bit | Gets or sets administrative retention holds, one hold per bit | |||
position. | position. | |||
</t> | </t> | |||
<t> | <t> | |||
This attribute allows one to 64 administrative holds, one hold | This attribute allows one to 64 administrative holds, one hold | |||
per bit on the attribute. If retention_hold is not zero, then | per bit on the attribute. If retention_hold is not zero, then | |||
the file MUST NOT be deleted, renamed, or modified, even if | the file <bcp14>MUST NOT</bcp14> be deleted, renamed, or modified, even i f | |||
the duration on enabled event or non-event-based retention has | the duration on enabled event or non-event-based retention has | |||
been reached. The server MAY restrict the modification of | been reached. The server <bcp14>MAY</bcp14> restrict the modification of | |||
retention_hold on the basis of the ACE4_WRITE_RETENTION_HOLD | retention_hold on the basis of the ACE4_WRITE_RETENTION_HOLD | |||
ACL permission. The enabling of administration retention | ACL permission. The enabling of administration retention | |||
holds does not prevent the enabling of event-based or | holds does not prevent the enabling of event-based or | |||
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 MUST fail with NFS4ERR_ACCESS. | the attempt <bcp14>MUST</bcp14> fail with NFS4ERR_ACCESS. | |||
</t> | </t> | |||
</section> | ||||
</section> | ||||
</section> | </section> | |||
</section> | <section anchor="acl" numbered="true" toc="default"> | |||
</section> | <name>Access Control Attributes</name> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <t> | |||
$ --> | ||||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | ||||
<!-- Copyright (C) The Internet Society (2006) --> | ||||
<section title="Access Control Attributes" anchor="acl"> | ||||
<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. | |||
</t> | </t> | |||
<section numbered="true" toc="default"> | ||||
<section title="Goals"> | <name>Goals</name> | |||
<t> | <t> | |||
ACLs and modes represent two well-established models for | ACLs and modes represent two well-established models for | |||
specifying permissions. This section specifies requirements | specifying permissions. This section specifies requirements | |||
that attempt to meet the following goals: | that attempt to meet the following goals: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If a server supports the mode attribute, it should provide | If a server supports the mode attribute, it should provide | |||
reasonable semantics to clients that only set and retrieve | reasonable semantics to clients that only set and retrieve | |||
the mode attribute. | the mode attribute. | |||
</t> | </li> | |||
<t> | <li> | |||
If a server supports ACL attributes, it should provide | If a server supports ACL attributes, it should provide | |||
reasonable semantics to clients that only set and retrieve | reasonable semantics to clients that only set and retrieve | |||
those attributes. | those attributes. | |||
</t> | </li> | |||
<t> | <li> | |||
On servers that support the mode attribute, if ACL | On servers that support the mode attribute, if ACL | |||
attributes have never been set on an object, via | attributes have never been set on an object, via | |||
inheritance or explicitly, the behavior should be | inheritance or explicitly, the behavior should be | |||
traditional UNIX-like behavior. | traditional UNIX-like behavior. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
On servers that support the mode attribute, if the ACL | On servers that support the mode attribute, if the ACL | |||
attributes have been previously set on an object, either | attributes have been previously set on an object, either | |||
explicitly or via inheritance: | explicitly or via inheritance: | |||
<list> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Setting only the mode attribute should effectively | Setting only the mode attribute should effectively | |||
control the traditional UNIX-like permissions of read, | control the traditional UNIX-like permissions of read, | |||
write, and execute on owner, owner_group, and other. | write, and execute on owner, owner_group, and other. | |||
</t> | </li> | |||
<t> | <li> | |||
Setting only the mode attribute should provide | Setting only the mode attribute should provide | |||
reasonable security. For example, setting a mode of | reasonable security. For example, setting a mode of | |||
000 should be enough to ensure that future OPEN operations for | 000 should be enough to ensure that future OPEN operations for | |||
OPEN4_SHARE_ACCESS_READ or OPEN4_SHARE_ACCESS_WRITE by any princ ipal fail, regardless of a | OPEN4_SHARE_ACCESS_READ or OPEN4_SHARE_ACCESS_WRITE by any princ ipal fail, regardless of a | |||
previously existing or inherited ACL. | previously existing or inherited ACL. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
<t> | <li> | |||
NFSv4.1 may introduce different | NFSv4.1 may introduce different | |||
semantics relating to the mode and ACL attributes, | semantics relating to the mode and ACL attributes, | |||
but it does not render invalid any previously | but it does not render invalid any previously | |||
existing implementations. Additionally, this | existing implementations. Additionally, this | |||
section provides clarifications based on previous | section provides clarifications based on previous | |||
implementations and discussions around them. | implementations and discussions around them. | |||
</t> | </li> | |||
<t> | <li> | |||
On servers that support both the mode and the acl or | On servers that support both the mode and the acl or | |||
dacl attributes, the server must keep the two consistent | dacl attributes, the server must keep the two consistent | |||
with each other. The value of the mode attribute (with | with each other. The value of the mode attribute (with | |||
the exception of the three high-order bits described in | the exception of the three high-order bits described in | |||
<xref target="attrdef_mode" />) must be determined entirely | <xref target="attrdef_mode" format="default"/>) must be determined e ntirely | |||
by the value of the ACL, so that use of the mode is | by the value of the ACL, so that use of the mode is | |||
never required for anything other than setting the | never required for anything other than setting the | |||
three high-order bits. See <xref target="setattr" /> | three high-order bits. See <xref target="setattr" format="default"/ > | |||
for exact requirements. | for exact requirements. | |||
</t> | </li> | |||
<t> | <li> | |||
When a mode attribute is set on an object, the ACL | When a mode attribute is set on an object, the ACL | |||
attributes may need to be modified in order to not conflict | attributes may need to be modified in order to not conflict | |||
with the new mode. In such cases, it is desirable that the | with the new mode. In such cases, it is desirable that the | |||
ACL keep as much information as possible. This includes | ACL keep as much information as possible. This includes | |||
information about inheritance, AUDIT and ALARM ACEs, and | information about inheritance, AUDIT and ALARM ACEs, and | |||
permissions granted and denied that do not conflict with | permissions granted and denied that do not conflict with | |||
the new mode. | the new mode. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section numbered="true" toc="default"> | |||
<name>File Attributes Discussion</name> | ||||
<section title="File Attributes Discussion"> | <section anchor="attrdef_acl" numbered="true" toc="default"> | |||
<section anchor="attrdef_acl" | <name>Attribute 12: acl</name> | |||
title="Attribute 12: acl"> | <t> | |||
<t> | ||||
The NFSv4.1 ACL attribute contains an array of Access | The NFSv4.1 ACL attribute contains an array of Access | |||
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> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
typedef uint32_t acetype4; | typedef uint32_t acetype4; | |||
</artwork> | ||||
</figure> | ||||
<figure> | ||||
<artwork> | ||||
typedef uint32_t aceflag4; | typedef uint32_t aceflag4; | |||
</artwork> | ||||
</figure> | ||||
<figure> | ||||
<artwork> | ||||
typedef uint32_t acemask4; | typedef uint32_t acemask4; | |||
</artwork> | ||||
</figure> | ||||
<figure> | ||||
<artwork> | ||||
struct nfsace4 { | struct nfsace4 { | |||
acetype4 type; | acetype4 type; | |||
aceflag4 flag; | aceflag4 flag; | |||
acemask4 access_mask; | acemask4 access_mask; | |||
utf8str_mixed who; | utf8str_mixed who; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
<t> | ||||
To determine if a request succeeds, the server processes | To determine if a request succeeds, the server processes | |||
each nfsace4 entry in order. Only ACEs that have a "who" | each nfsace4 entry in order. Only ACEs that have a "who" | |||
that matches the requester are considered. Each ACE is | that matches the requester are considered. Each ACE is | |||
processed until all of the bits of the requester's access | processed until all of the bits of the requester's access | |||
have been ALLOWED. Once a bit (see below) has been ALLOWED | have been ALLOWED. Once a bit (see below) has been ALLOWED | |||
by an ACCESS_ALLOWED_ACE, it is no longer considered in the | by an ACCESS_ALLOWED_ACE, it is no longer considered in the | |||
processing of later ACEs. If an ACCESS_DENIED_ACE is | processing of later ACEs. If an ACCESS_DENIED_ACE is | |||
encountered where the requester's access still has unALLOWED | encountered where the requester's access still has unALLOWED | |||
bits in common with the "access_mask" of the ACE, the | bits in common with the "access_mask" of the ACE, the | |||
request is denied. When the ACL is fully processed, if | request is denied. When the ACL is fully processed, if | |||
there are bits in the requester's mask that have not been | there are bits in the requester's mask that have not been | |||
ALLOWED or DENIED, access is denied. | ALLOWED or DENIED, access is denied. | |||
</t> | </t> | |||
<t> | <t> | |||
Unlike the ALLOW and DENY ACE types, the ALARM and AUDIT ACE | Unlike the ALLOW and DENY ACE types, the ALARM and AUDIT ACE | |||
types do not affect a requester's access, and instead are | types do not affect a requester's access, and instead are | |||
for triggering events as a result of a requester's access | for triggering events as a result of a requester's access | |||
attempt. Therefore, AUDIT and ALARM ACEs are processed only | attempt. Therefore, AUDIT and ALARM ACEs are processed only | |||
after processing ALLOW and DENY ACEs. | after processing ALLOW and DENY ACEs. | |||
</t> | </t> | |||
<t> | <t> | |||
The NFSv4.1 ACL model is quite rich. Some server | The NFSv4.1 ACL model is quite rich. Some server | |||
platforms may provide access-control functionality that goes | platforms may provide access-control functionality that goes | |||
beyond the UNIX-style mode attribute, but that is not as | beyond the UNIX-style mode attribute, but that is not as | |||
rich as the NFS ACL model. So that users can take advantage | rich as the NFS ACL model. So that users can take advantage | |||
of this more limited functionality, the server may support | of this more limited functionality, the server may support | |||
the acl attributes by mapping between its ACL model and the | the acl attributes by mapping between its ACL model and the | |||
NFSv4.1 ACL model. Servers must ensure that the ACL | NFSv4.1 ACL model. Servers must ensure that the ACL | |||
they actually store or enforce is at least as strict as the | they actually store or enforce is at least as strict as the | |||
NFSv4 ACL that was set. It is tempting to accomplish this | NFSv4 ACL that was set. It is tempting to accomplish this | |||
by rejecting any ACL that falls outside the small set that | by rejecting any ACL that falls outside the small set that | |||
skipping to change at line 8503 ¶ | skipping to change at line 8754 ¶ | |||
of having a common NFSv4 ACL protocol. Therefore, servers | of having a common NFSv4 ACL protocol. Therefore, servers | |||
should accept every ACL that they can without compromising | should accept every ACL that they can without compromising | |||
security. To help accomplish this, servers may make a | security. To help accomplish this, servers may make a | |||
special exception, in the case of unsupported permission | special exception, in the case of unsupported permission | |||
bits, to the rule that bits not ALLOWED or DENIED by an ACL | bits, to the rule that bits not ALLOWED or DENIED by an ACL | |||
must be denied. For example, a UNIX-style server might | must be denied. For example, a UNIX-style server might | |||
choose to silently allow read attribute permissions even | choose to silently allow read attribute permissions even | |||
though an ACL does not explicitly allow those permissions. | though an ACL does not explicitly allow those permissions. | |||
(An ACL that explicitly denies permission to read attributes | (An ACL that explicitly denies permission to read attributes | |||
should still be rejected.) | should still be rejected.) | |||
</t> | </t> | |||
<t> | <t> | |||
The situation is complicated by the fact that a server may | The situation is complicated by the fact that a server may | |||
have multiple modules that enforce ACLs. For example, the | have multiple modules that enforce ACLs. For example, the | |||
enforcement for NFSv4.1 access may be different from, | enforcement for NFSv4.1 access may be different from, | |||
but not weaker than, the enforcement for local access, and | but not weaker than, the enforcement for local access, and | |||
both may be different from the enforcement for access | both may be different from the enforcement for access | |||
through other protocols such as SMB (Server Message Block). So it may be useful for | through other protocols such as SMB (Server Message Block). So it may be useful for | |||
a server to accept an ACL even if not all of its modules are | a server to accept an ACL even if not all of its modules are | |||
able to support it. | able to support it. | |||
</t> | </t> | |||
<t> | <t> | |||
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 title="ACE Type"> | <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="xdr"><![CDATA[ | ||||
<figure> | ||||
<artwork> | ||||
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; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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. | |||
</t> | </t> | |||
<texttable> | <table align="center"> | |||
<ttcol>Value</ttcol> | <thead> | |||
<ttcol>Abbreviation</ttcol> | <tr> | |||
<ttcol>Description</ttcol> | <th align="left">Value</th> | |||
<c>ACE4_ACCESS_ALLOWED_ACE_TYPE</c> | <th align="left">Abbreviation</th> | |||
<c>ALLOW</c> | <th align="left">Description</th> | |||
<c> | </tr> | |||
</thead> | ||||
<tbody> | ||||
<tr> | ||||
<td align="left">ACE4_ACCESS_ALLOWED_ACE_TYPE</td> | ||||
<td align="left">ALLOW</td> | ||||
<td align="left"> | ||||
Explicitly grants the access defined in acemask4 to | Explicitly grants the access defined in acemask4 to | |||
the file or directory. | the file or directory. | |||
</c> | </td> | |||
<c>ACE4_ACCESS_DENIED_ACE_TYPE</c> | </tr> | |||
<c>DENY</c> | <tr> | |||
<c> | <td align="left">ACE4_ACCESS_DENIED_ACE_TYPE</td> | |||
<td align="left">DENY</td> | ||||
<td align="left"> | ||||
Explicitly denies the access defined in acemask4 to | Explicitly denies the access defined in acemask4 to | |||
the file or directory. | the file or directory. | |||
</c> | </td> | |||
<c>ACE4_SYSTEM_AUDIT_ACE_TYPE</c> | </tr> | |||
<c>AUDIT</c> | <tr> | |||
<c> | <td align="left">ACE4_SYSTEM_AUDIT_ACE_TYPE</td> | |||
<td align="left">AUDIT</td> | ||||
<td align="left"> | ||||
Log (in a system-dependent way) any access attempt to | Log (in a system-dependent way) any access attempt to | |||
a file or directory that uses any of the access | a file or directory that uses any of the access | |||
methods specified in acemask4. | methods specified in acemask4. | |||
</c> | </td> | |||
<c>ACE4_SYSTEM_ALARM_ACE_TYPE</c> | </tr> | |||
<c>ALARM</c> | <tr> | |||
<c> | <td align="left">ACE4_SYSTEM_ALARM_ACE_TYPE</td> | |||
<td align="left">ALARM</td> | ||||
<td align="left"> | ||||
Generate an alarm (in a system-dependent way) when any | Generate an alarm (in a system-dependent way) when any | |||
access attempt is made to a file or directory for the | access attempt is made to a file or directory for the | |||
access methods specified in acemask4. | access methods specified in acemask4. | |||
</c> | </td> | |||
</texttable> | </tr> | |||
</tbody> | ||||
</table> | ||||
<t> | <t> | |||
The "Abbreviation" column denotes how the | The "Abbreviation" column denotes how the | |||
types will be referred to throughout the rest of this | types will be referred to throughout the rest of this | |||
section. | section. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="attrdef_aclsupport" | <section anchor="attrdef_aclsupport" numbered="true" toc="default"> | |||
title="Attribute 13: aclsupport"> | <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="xdr"><![CDATA[ | ||||
<figure> | ||||
<artwork> | ||||
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; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
<t> | ||||
Servers that support either the ALLOW or DENY ACE type | Servers that support either the ALLOW or DENY ACE type | |||
SHOULD support both ALLOW and DENY ACE types. | <bcp14>SHOULD</bcp14> support both ALLOW and DENY ACE types. | |||
</t> | </t> | |||
<t> | <t> | |||
Clients should not attempt to set an ACE unless the server | Clients should not attempt to set an ACE unless the server | |||
claims support for that ACE type. If the server receives a | claims support for that ACE type. If the server receives a | |||
request to set an ACE that it cannot store, it MUST reject | request to set an ACE that it cannot store, it <bcp14>MUST</bcp14> r eject | |||
the request with NFS4ERR_ATTRNOTSUPP. If the server | the request with NFS4ERR_ATTRNOTSUPP. If the server | |||
receives a request to set an ACE that it can store but | receives a request to set an ACE that it can store but | |||
cannot enforce, the server SHOULD reject the request with | cannot enforce, the server <bcp14>SHOULD</bcp14> reject the request with | |||
NFS4ERR_ATTRNOTSUPP. | NFS4ERR_ATTRNOTSUPP. | |||
</t> | </t> | |||
<t> | <t> | |||
Support for any of the ACL attributes is | Support for any of the ACL attributes is | |||
optional (albeit RECOMMENDED). | optional (albeit <bcp14>RECOMMENDED</bcp14>). | |||
However, a server that supports either of the new ACL | However, a server that supports either of the new ACL | |||
attributes (dacl or sacl) MUST allow use of the new ACL | attributes (dacl or sacl) <bcp14>MUST</bcp14> allow use of the new A CL | |||
attributes to access all of the ACE types that it | attributes to access all of the ACE types that it | |||
supports. In other words, if such a server supports ALLOW | supports. In other words, if such a server supports ALLOW | |||
or DENY ACEs, then it MUST support the dacl attribute, and | or DENY ACEs, then it <bcp14>MUST</bcp14> support the dacl attribute | |||
if it supports AUDIT or ALARM ACEs, then it MUST support | , and | |||
if it supports AUDIT or ALARM ACEs, then it <bcp14>MUST</bcp14> supp | ||||
ort | ||||
the sacl attribute. | the sacl attribute. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="acemask" title="ACE Access Mask"> | <section anchor="acemask" numbered="true" toc="default"> | |||
<t> | <name>ACE Access Mask</name> | |||
<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="xdr"><![CDATA[ | ||||
<figure> | ||||
<artwork> | ||||
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; | |||
const ACE4_READ_ATTRIBUTES = 0x00000080; | const ACE4_READ_ATTRIBUTES = 0x00000080; | |||
const ACE4_WRITE_ATTRIBUTES = 0x00000100; | const ACE4_WRITE_ATTRIBUTES = 0x00000100; | |||
const ACE4_WRITE_RETENTION = 0x00000200; | const ACE4_WRITE_RETENTION = 0x00000200; | |||
const ACE4_WRITE_RETENTION_HOLD = 0x00000400; | const ACE4_WRITE_RETENTION_HOLD = 0x00000400; | |||
const ACE4_DELETE = 0x00010000; | const ACE4_DELETE = 0x00010000; | |||
const ACE4_READ_ACL = 0x00020000; | const ACE4_READ_ACL = 0x00020000; | |||
const ACE4_WRITE_ACL = 0x00040000; | const ACE4_WRITE_ACL = 0x00040000; | |||
const ACE4_WRITE_OWNER = 0x00080000; | const ACE4_WRITE_OWNER = 0x00080000; | |||
const ACE4_SYNCHRONIZE = 0x00100000; | const ACE4_SYNCHRONIZE = 0x00100000; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
<t> | ||||
Note that some masks have coincident values, for | Note that some masks have coincident values, for | |||
example, ACE4_READ_DATA and ACE4_LIST_DIRECTORY. | example, ACE4_READ_DATA and ACE4_LIST_DIRECTORY. | |||
The mask entries ACE4_LIST_DIRECTORY, | The mask entries ACE4_LIST_DIRECTORY, | |||
ACE4_ADD_FILE, and ACE4_ADD_SUBDIRECTORY are | ACE4_ADD_FILE, and ACE4_ADD_SUBDIRECTORY are | |||
intended to be used with directory objects, | intended to be used with directory objects, | |||
while ACE4_READ_DATA, ACE4_WRITE_DATA, and | while ACE4_READ_DATA, ACE4_WRITE_DATA, and | |||
ACE4_APPEND_DATA are intended to be used with | ACE4_APPEND_DATA are intended to be used with | |||
non-directory objects. | non-directory objects. | |||
</t> | </t> | |||
<section title="Discussion of Mask Attributes"> | <section numbered="true" toc="default"> | |||
<t> | <name>Discussion of Mask Attributes</name> | |||
<list style="hanging"> | ||||
<t hangText="ACE4_READ_DATA"> | <t>ACE4_READ_DATA</t> | |||
<list style="hanging"> | <ul empty="true"><li> <dl newline="true" spacing="normal"> | |||
<t hangText="Operation(s) affected:"> | <dt>Operation(s) affected:</dt> | |||
<list style="hanging"> | <dd><t>READ</t> | |||
<t hangText="READ" /> | <t>OPEN</t></dd> | |||
<t hangText="OPEN" /> | <dt>Discussion:</dt> | |||
</list> | <dd> | |||
</t> | <t> | |||
<t hangText="Discussion:"> | ||||
<vspace blankLines='1' /> | ||||
Permission to read the data of the file. | Permission to read the data of the file. | |||
<vspace blankLines='1' /> | </t> | |||
Servers SHOULD allow a user the ability to read the data | <t> | |||
Servers <bcp14>SHOULD</bcp14> allow a user the ability to r | ||||
ead the data | ||||
of the file when only the ACE4_EXECUTE access mask bit is | of the file when only the ACE4_EXECUTE access mask bit is | |||
allowed. | allowed. | |||
</t> | </t> | |||
</list> | </dd> | |||
</t> | </dl></li> | |||
</ul> | ||||
<t hangText="ACE4_LIST_DIRECTORY"> | <t>ACE4_LIST_DIRECTORY</t> | |||
<list style="hanging"> | <ul empty="true"><li> | |||
<t hangText="Operation(s) affected:"> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>Operation(s) affected:</dt> | |||
<t hangText="READDIR" /> | <dd>READDIR</dd> | |||
</list> | ||||
</t> | <dt>Discussion:</dt> | |||
<t hangText="Discussion:"> | <dd> | |||
<vspace blankLines='1' /> | ||||
Permission to list the contents of a directory. | Permission to list the contents of a directory. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | </li> | |||
</ul> | ||||
<t hangText="ACE4_WRITE_DATA"> | <t>ACE4_WRITE_DATA</t> | |||
<list style="hanging"> | <ul empty="true"><li> | |||
<t hangText="Operation(s) affected:"> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>Operation(s) affected:</dt> | |||
<t hangText="WRITE" /> | <dd><t>WRITE</t> | |||
<t hangText="OPEN" /> | <t>OPEN</t> | |||
<t hangText="SETATTR of size" /> | <t>SETATTR of size</t> | |||
</list> | </dd> | |||
</t> | ||||
<t hangText="Discussion:"> | <dt>Discussion:</dt> | |||
<vspace blankLines='1' /> | <dd> | |||
Permission to modify a file's data. | Permission to modify a file's data. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | </li></ul> | |||
<t hangText="ACE4_ADD_FILE"> | <t>ACE4_ADD_FILE</t> | |||
<list style="hanging"> | <ul empty="true"><li> | |||
<t hangText="Operation(s) affected:"> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>Operation(s) affected:</dt> | |||
<t hangText="CREATE" /> | <dd><t>CREATE</t> | |||
<t hangText="LINK" /> | <t>LINK</t> | |||
<t hangText="OPEN" /> | <t>OPEN</t> | |||
<t hangText="RENAME" /> | <t>RENAME</t> | |||
</list> | </dd> | |||
</t> | ||||
<t hangText="Discussion:"> | <dt>Discussion:</dt> | |||
<vspace blankLines='1' /> | <dd> | |||
Permission to add a new file in a directory. | Permission to add a new file in a directory. | |||
The CREATE operation is affected when nfs_ftype4 | The CREATE operation is affected when nfs_ftype4 | |||
is NF4LNK, NF4BLK, NF4CHR, NF4SOCK, or | is NF4LNK, NF4BLK, NF4CHR, NF4SOCK, or | |||
NF4FIFO. (NF4DIR is not listed because it is | NF4FIFO. (NF4DIR is not listed because it is | |||
covered by ACE4_ADD_SUBDIRECTORY.) OPEN is | covered by ACE4_ADD_SUBDIRECTORY.) OPEN is | |||
affected when used to create a regular file. | affected when used to create a regular file. | |||
LINK and RENAME are always affected. | LINK and RENAME are always affected. | |||
</t> | </dd> | |||
</list> | </dl></li> | |||
</t> | </ul> | |||
<t hangText="ACE4_APPEND_DATA"> | <t>ACE4_APPEND_DATA</t> | |||
<list style="hanging"> | <ul empty="true"><li> | |||
<t hangText="Operation(s) affected:"> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>Operation(s) affected:</dt> | |||
<t hangText="WRITE" /> | <dd><t>WRITE</t> | |||
<t hangText="OPEN" /> | <t>OPEN</t> | |||
<t hangText="SETATTR of size" /> | <t>SETATTR of size</t> | |||
</list> | </dd> | |||
</t> | ||||
<t hangText="Discussion:"> | <dt>Discussion:</dt> | |||
<vspace blankLines='1' /> | <dd> | |||
The ability to modify a file's data, but only | The ability to modify a file's data, but only | |||
starting at EOF. This allows for the notion of | starting at EOF. This allows for the notion of | |||
append-only files, by allowing ACE4_APPEND_DATA | append-only files, by allowing ACE4_APPEND_DATA | |||
and denying ACE4_WRITE_DATA to the same user or | and denying ACE4_WRITE_DATA to the same user or | |||
group. If a file has an ACL such as the one | group. If a file has an ACL such as the one | |||
described above and a WRITE request is made for | described above and a WRITE request is made for | |||
somewhere other than EOF, the server SHOULD | somewhere other than EOF, the server <bcp14>SHOULD</bcp14> | |||
return NFS4ERR_ACCESS. | return NFS4ERR_ACCESS. | |||
</t> | </dd> | |||
</list> | </dl></li> | |||
</t> | </ul> | |||
<t hangText="ACE4_ADD_SUBDIRECTORY"> | <t>ACE4_ADD_SUBDIRECTORY</t> | |||
<list style="hanging"> | <ul empty="true"><li> | |||
<t hangText="Operation(s) affected:"> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>Operation(s) affected:</dt> | |||
<t hangText="CREATE" /> | <dd><t>CREATE</t> | |||
<t hangText="RENAME" /> | <t>RENAME</t></dd> | |||
</list> | ||||
</t> | <dt>Discussion:</dt> | |||
<t hangText="Discussion:"> | <dd> | |||
<vspace blankLines='1' /> | ||||
Permission to create a subdirectory in a | Permission to create a subdirectory in a | |||
directory. The CREATE operation is affected | directory. The CREATE operation is affected | |||
when nfs_ftype4 is NF4DIR. The RENAME operation | when nfs_ftype4 is NF4DIR. The RENAME operation | |||
is always affected. | is always affected. | |||
</t> | </dd> | |||
</list> | </dl></li> | |||
</t> | </ul> | |||
<t hangText="ACE4_READ_NAMED_ATTRS"> | <t>ACE4_READ_NAMED_ATTRS</t> | |||
<list style="hanging"> | <ul empty="true"><li> | |||
<t hangText="Operation(s) affected:"> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>Operation(s) affected:</dt> | |||
<t hangText="OPENATTR" /> | <dd><t>OPENATTR</t></dd> | |||
</list> | ||||
</t> | <dt>Discussion:</dt> | |||
<t hangText="Discussion:"> | <dd> | |||
<vspace blankLines='1' /> | ||||
Permission to read the named attributes of a | Permission to read the named attributes of a | |||
file or to look up the named attribute | file or to look up the named attribute | |||
directory. OPENATTR is affected when it is not | directory. OPENATTR is affected when it is not | |||
used to create a named attribute directory. | used to create a named attribute directory. | |||
This is when 1) createdir is TRUE, but a named | This is when 1) createdir is TRUE, but a named | |||
attribute directory already exists, or 2) | attribute directory already exists, or 2) | |||
createdir is FALSE. | createdir is FALSE. | |||
</t> | </dd> | |||
</list> | </dl></li> | |||
</t> | </ul> | |||
<t hangText="ACE4_WRITE_NAMED_ATTRS"> | <t>ACE4_WRITE_NAMED_ATTRS</t> | |||
<list style="hanging"> | <ul empty="true"><li> | |||
<t hangText="Operation(s) affected:"> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>Operation(s) affected:</dt> | |||
<t hangText="OPENATTR" /> | <dd><t>OPENATTR</t> | |||
<t hangText="" /> | </dd> | |||
</list> | <dt>Discussion:</dt> | |||
</t> | <dd> | |||
<t hangText="Discussion:"> | ||||
<vspace blankLines='1' /> | ||||
Permission to write the named attributes of a | Permission to write the named attributes of a | |||
file or to create a named attribute directory. | file or to create a named attribute directory. | |||
OPENATTR is affected when it is used to create a | OPENATTR is affected when it is used to create a | |||
named attribute directory. This is when | named attribute directory. This is when | |||
createdir is TRUE and no named attribute | createdir is TRUE and no named attribute | |||
directory exists. The ability to check whether | directory exists. The ability to check whether | |||
or not a named attribute directory exists | or not a named attribute directory exists | |||
depends on the ability to look it up; therefore, | depends on the ability to look it up; therefore, | |||
users also need the ACE4_READ_NAMED_ATTRS | users also need the ACE4_READ_NAMED_ATTRS | |||
permission in order to create a named attribute | permission in order to create a named attribute | |||
directory. | directory. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | </li> | |||
</ul> | ||||
<t hangText="ACE4_EXECUTE"> | <t>ACE4_EXECUTE</t> | |||
<list style="hanging"> | <ul empty="true"><li> | |||
<t hangText="Operation(s) affected:"> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>Operation(s) affected:</dt> | |||
<t hangText="READ" /> | <dd><t>READ</t> | |||
<t hangText="OPEN" /> | <t>OPEN</t> | |||
<t hangText="REMOVE" /> | <t>REMOVE</t> | |||
<t hangText="RENAME" /> | <t>RENAME</t> | |||
<t hangText="LINK" /> | <t>LINK</t> | |||
<t hangText="CREATE" /> | <t>CREATE</t> | |||
</list> | </dd> | |||
</t> | ||||
<t hangText="Discussion:"> | <dt>Discussion:</dt> | |||
<vspace blankLines='1' /> | <dd> | |||
<t> | ||||
Permission to execute a file. | Permission to execute a file. | |||
<vspace blankLines='1' /> | </t> | |||
Servers SHOULD allow a | <t> | |||
Servers <bcp14>SHOULD</bcp14> allow a | ||||
user the ability to read the data of the file | user the ability to read the data of the file | |||
when only the ACE4_EXECUTE access mask bit is | when only the ACE4_EXECUTE access mask bit is | |||
allowed. This is because there is no way to | allowed. This is because there is no way to | |||
execute a file without reading the contents. | execute a file without reading the contents. | |||
Though a server may treat ACE4_EXECUTE and | Though a server may treat ACE4_EXECUTE and | |||
ACE4_READ_DATA bits identically when deciding to | ACE4_READ_DATA bits identically when deciding to | |||
permit a READ operation, it SHOULD still allow | permit a READ operation, it <bcp14>SHOULD</bcp14> still all ow | |||
the two bits to be set independently in ACLs, | the two bits to be set independently in ACLs, | |||
and MUST distinguish between them when replying | and <bcp14>MUST</bcp14> distinguish between them when reply ing | |||
to ACCESS operations. In particular, servers | to ACCESS operations. In particular, servers | |||
SHOULD NOT silently turn on one of the two bits | <bcp14>SHOULD NOT</bcp14> silently turn on one of the two b its | |||
when the other is set, as that would make it | when the other is set, as that would make it | |||
impossible for the client to correctly enforce | impossible for the client to correctly enforce | |||
the distinction between read and execute | the distinction between read and execute | |||
permissions. | permissions. | |||
<vspace blankLines='1' /> | </t> | |||
As an example, following a SETATTR of the following ACL: | <t>As an example, following a SETATTR of the following ACL: | |||
<vspace blankLines='1' /> | </t> | |||
nfsuser:ACE4_EXECUTE:ALLOW | <ul empty="true"> | |||
<vspace blankLines='1' /> | <li>nfsuser:ACE4_EXECUTE:ALLOW</li> | |||
A subsequent GETATTR of ACL for that file SHOULD return: | </ul> | |||
<vspace blankLines='1' /> | <t> | |||
nfsuser:ACE4_EXECUTE:ALLOW | A subsequent GETATTR of ACL for that file <bcp14>SHOULD</bc | |||
<vspace blankLines='1' /> | p14> return: | |||
</t> | ||||
<ul empty="true"> | ||||
<li>nfsuser:ACE4_EXECUTE:ALLOW</li> | ||||
</ul> | ||||
<t> | ||||
Rather than: | Rather than: | |||
<vspace blankLines='1' /> | </t> | |||
<ul empty="true"> | ||||
<li> | ||||
nfsuser:ACE4_EXECUTE/ACE4_READ_DATA:ALLOW | nfsuser:ACE4_EXECUTE/ACE4_READ_DATA:ALLOW | |||
</t> | </li></ul> | |||
</list> | </dd> | |||
</t> | </dl></li> | |||
</ul> | ||||
<t hangText="ACE4_EXECUTE"> | <t>ACE4_EXECUTE</t> | |||
<list style="hanging"> | <ul empty="true"><li> | |||
<t hangText="Operation(s) affected:"> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>Operation(s) affected:</dt> | |||
<t hangText="LOOKUP" /> | <dd>LOOKUP</dd> | |||
</list> | ||||
</t> | <dt>Discussion:</dt> | |||
<t hangText="Discussion:"> | <dd> | |||
<vspace blankLines='1' /> | ||||
Permission to traverse/search a directory. | Permission to traverse/search a directory. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | </li></ul> | |||
<t hangText="ACE4_DELETE_CHILD"> | <t>ACE4_DELETE_CHILD</t> | |||
<list style="hanging"> | <ul empty="true"><li> | |||
<t hangText="Operation(s) affected:"> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>Operation(s) affected:</dt> | |||
<t hangText="REMOVE" /> | <dd><t>REMOVE</t> | |||
<t hangText="RENAME" /> | <t>RENAME</t></dd> | |||
</list> | ||||
</t> | <dt>Discussion:</dt> | |||
<t hangText="Discussion:"> | <dd> | |||
<vspace blankLines='1' /> | ||||
Permission to delete a file or directory within | Permission to delete a file or directory within | |||
a directory. | a directory. | |||
See <xref | See <xref target="delete-delete_child" format="default"/> | |||
target="delete-delete_child"/> | ||||
for information on ACE4_DELETE and | for information on ACE4_DELETE and | |||
ACE4_DELETE_CHILD interact. | ACE4_DELETE_CHILD interact. | |||
</dd> | ||||
</dl></li> | ||||
</ul> | ||||
</t> | <t>ACE4_READ_ATTRIBUTES</t> | |||
</list> | <ul empty="true"><li> | |||
</t> | <dl newline="true" spacing="normal"> | |||
<dt>Operation(s) affected:</dt> | ||||
<dd><t>GETATTR of file system object attributes</t> | ||||
<t>VERIFY</t> | ||||
<t>NVERIFY</t> | ||||
<t>READDIR</t></dd> | ||||
<t hangText="ACE4_READ_ATTRIBUTES"> | <dt>Discussion:</dt> | |||
<list style="hanging"> | <dd> | |||
<t hangText="Operation(s) affected:"> | ||||
<list style="hanging"> | ||||
<t hangText="GETATTR of file system object attributes" /> | ||||
<t hangText="VERIFY" /> | ||||
<t hangText="NVERIFY" /> | ||||
<t hangText="READDIR" /> | ||||
</list> | ||||
</t> | ||||
<t hangText="Discussion:"> | ||||
<vspace blankLines='1' /> | ||||
The ability to read basic attributes (non-ACLs) | The ability to read basic attributes (non-ACLs) | |||
of a file. On a UNIX system, basic attributes | of a file. On a UNIX system, basic attributes | |||
can be thought of as the stat-level attributes. | can be thought of as the stat-level attributes. | |||
Allowing this access mask bit would mean that the | Allowing this access mask bit would mean that the | |||
entity can execute "ls -l" and stat. If a | entity can execute "ls -l" and stat. If a | |||
READDIR operation requests attributes, this mask | READDIR operation requests attributes, this mask | |||
must be allowed for the READDIR to succeed. | must be allowed for the READDIR to succeed. | |||
</t> | </dd> | |||
</list> | </dl></li> | |||
</t> | </ul> | |||
<t hangText="ACE4_WRITE_ATTRIBUTES"> | <t>ACE4_WRITE_ATTRIBUTES</t> | |||
<list style="hanging"> | ||||
<t hangText="Operation(s) affected:"> | <ul empty="true"><li> | |||
<list style="hanging"> | <dl newline="true" spacing="normal"> | |||
<t hangText="SETATTR of time_access_set, time_backup," /> | <dt>Operation(s) affected:</dt> | |||
<t hangText="time_create, time_modify_set, mimetype, hidd | <dd><t>SETATTR of time_access_set, time_backup,</t> | |||
en, system" /> | <t>time_create, time_modify_set, mimetype, hidden, syste | |||
</list> | m</t></dd> | |||
</t> | ||||
<t hangText="Discussion:"> | <dt>Discussion:</dt> | |||
<vspace blankLines='1' /> | <dd> | |||
Permission to change the times associated with a | Permission to change the times associated with a | |||
file or directory to an arbitrary value. Also | file or directory to an arbitrary value. Also | |||
permission to change the mimetype, hidden, and | permission to change the mimetype, hidden, and | |||
system attributes. A user having | system attributes. A user having | |||
ACE4_WRITE_DATA or ACE4_WRITE_ATTRIBUTES will be | ACE4_WRITE_DATA or ACE4_WRITE_ATTRIBUTES will be | |||
allowed to set the times associated with a file | allowed to set the times associated with a file | |||
to the current server time. | to the current server time. | |||
</t> | </dd> | |||
</list> | </dl></li> | |||
</t> | </ul> | |||
<t hangText="ACE4_WRITE_RETENTION"> | <t>ACE4_WRITE_RETENTION</t> | |||
<list style="hanging"> | ||||
<t hangText="Operation(s) affected:"> | <ul empty="true"><li> | |||
<list style="hanging"> | <dl newline="true" spacing="normal"> | |||
<t hangText="SETATTR of retention_set, retentevt_set." /> | <dt>Operation(s) affected:</dt> | |||
</list> | <dd>SETATTR of retention_set, retentevt_set.</dd> | |||
</t> | ||||
<t hangText="Discussion:"> | <dt>Discussion:</dt> | |||
<vspace blankLines='1' /> | <dd> | |||
Permission to modify the durations of event and | Permission to modify the durations of event and | |||
non-event-based retention. Also permission to | non-event-based retention. Also permission to | |||
enable event and non-event-based retention. A | enable event and non-event-based retention. A | |||
server MAY behave such that setting | server <bcp14>MAY</bcp14> behave such that setting | |||
ACE4_WRITE_ATTRIBUTES allows | ACE4_WRITE_ATTRIBUTES allows | |||
ACE4_WRITE_RETENTION. | ACE4_WRITE_RETENTION. | |||
</t> | </dd> | |||
</list> | </dl></li> | |||
</t> | </ul> | |||
<t hangText="ACE4_WRITE_RETENTION_HOLD"> | <t>ACE4_WRITE_RETENTION_HOLD</t> | |||
<list style="hanging"> | <ul empty="true"><li> | |||
<t hangText="Operation(s) affected:"> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>Operation(s) affected:</dt> | |||
<t hangText="SETATTR of retention_hold." /> | <dd>SETATTR of retention_hold.</dd> | |||
</list> | <dt>Discussion:</dt> | |||
</t> | <dd> | |||
<t hangText="Discussion:"> | ||||
<vspace blankLines='1' /> | ||||
Permission to modify the administration | Permission to modify the administration | |||
retention holds. A server MAY map | retention holds. A server <bcp14>MAY</bcp14> map | |||
ACE4_WRITE_ATTRIBUTES to | ACE4_WRITE_ATTRIBUTES to | |||
ACE_WRITE_RETENTION_HOLD. | ACE_WRITE_RETENTION_HOLD. | |||
</t> | </dd> | |||
</list> | </dl></li> | |||
</t> | </ul> | |||
<t hangText="ACE4_DELETE"> | ||||
<list style="hanging"> | ||||
<t hangText="Operation(s) affected:"> | ||||
<list style="hanging"> | ||||
<t hangText="REMOVE" /> | ||||
</list> | ||||
</t> | ||||
<t hangText="Discussion:"> | ||||
<vspace blankLines='1' /> | ||||
<t>ACE4_DELETE</t> | ||||
<ul empty="true"><li> | ||||
<dl newline="true" spacing="normal"> | ||||
<dt>Operation(s) affected:</dt> | ||||
<dd>REMOVE</dd> | ||||
<dt>Discussion:</dt> | ||||
<dd> | ||||
Permission to delete the | Permission to delete the | |||
file or directory. | file or directory. | |||
See <xref | See <xref target="delete-delete_child" format="default"/> | |||
target="delete-delete_child"/> | ||||
for information on ACE4_DELETE and | for information on ACE4_DELETE and | |||
ACE4_DELETE_CHILD interact. | ACE4_DELETE_CHILD interact. | |||
</dd> | ||||
</dl></li> | ||||
</ul> | ||||
</t> | <t>ACE4_READ_ACL</t> | |||
</list> | <ul empty="true"><li> | |||
</t> | <dl newline="true" spacing="normal"> | |||
<dt>Operation(s) affected:</dt> | ||||
<dd><t>GETATTR of acl, dacl, or sacl</t> | ||||
<t>NVERIFY</t> | ||||
<t>VERIFY</t></dd> | ||||
<t hangText="ACE4_READ_ACL"> | <dt>Discussion:</dt> | |||
<list style="hanging"> | <dd> | |||
<t hangText="Operation(s) affected:"> | ||||
<list style="hanging"> | ||||
<t hangText="GETATTR of acl, dacl, or sacl" /> | ||||
<t hangText="NVERIFY" /> | ||||
<t hangText="VERIFY" /> | ||||
</list> | ||||
</t> | ||||
<t hangText="Discussion:"> | ||||
<vspace blankLines='1' /> | ||||
Permission to read the ACL. | Permission to read the ACL. | |||
</t> | </dd> | |||
</list> | </dl></li> | |||
</t> | </ul> | |||
<t hangText="ACE4_WRITE_ACL"> | <t>ACE4_WRITE_ACL</t> | |||
<list style="hanging"> | <ul empty="true"><li> | |||
<t hangText="Operation(s) affected:"> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>Operation(s) affected:</dt> | |||
<t hangText="SETATTR of acl and mode" /> | <dd>SETATTR of acl and mode</dd> | |||
</list> | <dt>Discussion:</dt> | |||
</t> | <dd>Permission to write the acl and mode attributes.</dd> | |||
<t hangText="Discussion:"> | </dl></li> | |||
<vspace blankLines='1' /> | </ul> | |||
Permission to write the acl and mode attributes. | ||||
</t> | ||||
</list> | ||||
</t> | ||||
<t hangText="ACE4_WRITE_OWNER"> | <t>ACE4_WRITE_OWNER</t> | |||
<list style="hanging"> | <ul empty="true"><li> | |||
<t hangText="Operation(s) affected:"> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>Operation(s) affected:</dt> | |||
<t hangText="SETATTR of owner and owner_group" /> | <dd>SETATTR of owner and owner_group</dd> | |||
</list> | <dt>Discussion:</dt> | |||
</t> | <dd> | |||
<t hangText="Discussion:"> | ||||
<vspace blankLines='1' /> | ||||
Permission to write the owner and owner_group | Permission to write the owner and owner_group | |||
attributes. On UNIX systems, this is the | attributes. On UNIX systems, this is the | |||
ability to execute chown() and chgrp(). | ability to execute chown() and chgrp(). | |||
</t> | </dd> | |||
</list> | </dl></li> | |||
</t> | </ul> | |||
<t hangText="ACE4_SYNCHRONIZE"> | <t>ACE4_SYNCHRONIZE</t> | |||
<list style="hanging"> | <ul empty="true"><li> | |||
<t hangText="Operation(s) affected:"> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>Operation(s) affected:</dt> | |||
<t hangText="NONE" /> | <dd>NONE</dd> | |||
</list> | <dt>Discussion:</dt> | |||
</t> | <dd> | |||
<t hangText="Discussion:"> | <t> | |||
<vspace blankLines='1' /> | ||||
Permission to use the file object as a | Permission to use the file object as a | |||
synchronization primitive for interprocess | synchronization primitive for interprocess | |||
communication. This permission is not enforced | communication. This permission is not enforced | |||
or interpreted by the NFSv4.1 server on behalf of | or interpreted by the NFSv4.1 server on behalf of | |||
the client. | the client. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
Typically, the ACE4_SYNCHRONIZE permission is | Typically, the ACE4_SYNCHRONIZE permission is | |||
only meaningful on local file systems, i.e., | only meaningful on local file systems, i.e., | |||
file systems not accessed via NFSv4.1. The reason | file systems not accessed via NFSv4.1. The reason | |||
that the permission bit exists is that some operating | that the permission bit exists is that some operating | |||
environments, such as Windows, use ACE4_SYNCHRONIZE. | environments, such as Windows, use ACE4_SYNCHRONIZE. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
For example, if a client copies a file that has | For example, if a client copies a file that has | |||
ACE4_SYNCHRONIZE set from a local file system to | ACE4_SYNCHRONIZE set from a local file system to | |||
an NFSv4.1 server, and then later copies the file | an NFSv4.1 server, and then later copies the file | |||
from the NFSv4.1 server to a local file system, | from the NFSv4.1 server to a local file system, | |||
it is likely that if ACE4_SYNCHRONIZE was set | it is likely that if ACE4_SYNCHRONIZE was set | |||
in the original file, the client will want it | in the original file, the client will want it | |||
set in the second copy. The first copy will not | set in the second copy. The first copy will not | |||
have the permission set unless the NFSv4.1 server | have the permission set unless the NFSv4.1 server | |||
has the means to set the ACE4_SYNCHRONIZE bit. The | has the means to set the ACE4_SYNCHRONIZE bit. The | |||
second copy will not have the permission set unless | second copy will not have the permission set unless | |||
the NFSv4.1 server has the means to retrieve the | the NFSv4.1 server has the means to retrieve the | |||
ACE4_SYNCHRONIZE bit. | ACE4_SYNCHRONIZE bit. | |||
</t> | ||||
</t> | </dd> | |||
</list> | </dl></li> | |||
</t> | </ul> | |||
<t> | ||||
</list> | ||||
</t> | ||||
<t> | ||||
Server implementations need not provide the granularity | Server implementations need not provide the granularity | |||
of control that is implied by this list of masks. For | of control that is implied by this list of masks. For | |||
example, POSIX-based systems might not distinguish | example, POSIX-based systems might not distinguish | |||
ACE4_APPEND_DATA (the ability to append to a file) from | ACE4_APPEND_DATA (the ability to append to a file) from | |||
ACE4_WRITE_DATA (the ability to modify existing | ACE4_WRITE_DATA (the ability to modify existing | |||
contents); both masks would be tied to a single "write" | contents); both masks would be tied to a single "write" | |||
permission <xref target="chmod"/>. When such a server returns attr ibutes to the | permission <xref target="chmod" format="default"/>. When such a se rver returns attributes to the | |||
client, it would show both ACE4_APPEND_DATA and | client, it would show both ACE4_APPEND_DATA and | |||
ACE4_WRITE_DATA if and only if the write permission is | ACE4_WRITE_DATA if and only if the write permission is | |||
enabled. | enabled. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
If a server receives a SETATTR request that it cannot | If a server receives a SETATTR request that it cannot | |||
accurately implement, it should err in the direction of | accurately implement, it should err in the direction of | |||
more restricted access, except in the previously | more restricted access, except in the previously | |||
discussed cases of execute and read. For example, | discussed cases of execute and read. For example, | |||
suppose a server cannot distinguish overwriting data | suppose a server cannot distinguish overwriting data | |||
from appending new data, as described in the previous | from appending new data, as described in the previous | |||
paragraph. If a client submits an ALLOW ACE where | paragraph. If a client submits an ALLOW ACE where | |||
ACE4_APPEND_DATA is set but ACE4_WRITE_DATA is not (or | ACE4_APPEND_DATA is set but ACE4_WRITE_DATA is not (or | |||
vice versa), the server should either turn off | vice versa), the server should either turn off | |||
ACE4_APPEND_DATA or reject the request with | ACE4_APPEND_DATA or reject the request with | |||
NFS4ERR_ATTRNOTSUPP. | NFS4ERR_ATTRNOTSUPP. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="delete-delete_child" numbered="true" toc="default"> | ||||
<section anchor="delete-delete_child" title="ACE4_DELETE vs. ACE4_DELE | <name>ACE4_DELETE vs. ACE4_DELETE_CHILD</name> | |||
TE_CHILD"> | <t> | |||
<t> | ||||
Two access mask bits govern the ability to delete a | Two access mask bits govern the ability to delete a | |||
directory entry: ACE4_DELETE on the object | directory entry: ACE4_DELETE on the object | |||
itself (the "target") and ACE4_DELETE_CHILD on | itself (the "target") and ACE4_DELETE_CHILD on | |||
the containing directory (the "parent"). | the containing directory (the "parent"). | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
Many systems also take the "sticky bit" (MODE4_SVTX) | Many systems also take the "sticky bit" (MODE4_SVTX) | |||
on a directory to allow unlink only to a user that | on a directory to allow unlink only to a user that | |||
owns either the target or the parent; on some | owns either the target or the parent; on some | |||
such systems the decision also depends on | such systems the decision also depends on | |||
whether the target is writable. | whether the target is writable. | |||
</t> | </t> | |||
<t> | ||||
<t> | Servers <bcp14>SHOULD</bcp14> allow unlink if either ACE4_DELETE | |||
Servers SHOULD allow unlink if either ACE4_DELETE | ||||
is permitted on the target, or ACE4_DELETE_CHILD is | is permitted on the target, or ACE4_DELETE_CHILD is | |||
permitted on the parent. (Note that this is | permitted on the parent. (Note that this is | |||
true even if the parent or target explicitly | true even if the parent or target explicitly | |||
denies one of these permissions.) | denies one of these permissions.) | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
If the ACLs in question neither explicitly ALLOW | If the ACLs in question neither explicitly ALLOW | |||
nor DENY either of the above, and if MODE4_SVTX is | nor DENY either of the above, and if MODE4_SVTX is | |||
not set on the parent, then the server SHOULD allow | not set on the parent, then the server <bcp14>SHOULD</bcp14> allow | |||
the removal if and only if ACE4_ADD_FILE is permitted. | the removal if and only if ACE4_ADD_FILE is permitted. | |||
In the case where MODE4_SVTX is set, the server | In the case where MODE4_SVTX is set, the server | |||
may also require the remover to own either the parent | may also require the remover to own either the parent | |||
or the target, or may require the target to be | or the target, or may require the target to be | |||
writable. | writable. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
This allows servers to support something close to | This allows servers to support something close to | |||
traditional UNIX-like semantics, with ACE4_ADD_FILE | traditional UNIX-like semantics, with ACE4_ADD_FILE | |||
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" title="ACE flag"> | <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: | |||
<figure> | </t> | |||
<artwork> | <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; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
A server need not support any of these flags. If the | A server need not support any of these flags. If the | |||
server supports flags that are similar to, but not | server supports flags that are similar to, but not | |||
exactly the same as, these flags, the implementation | exactly the same as, these flags, the implementation | |||
may define a mapping between the protocol-defined | may define a mapping between the protocol-defined | |||
flags and the implementation-defined flags. | flags and the implementation-defined flags. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
For example, suppose a client tries to set an ACE with | For example, suppose a client tries to set an ACE with | |||
ACE4_FILE_INHERIT_ACE set but not | ACE4_FILE_INHERIT_ACE set but not | |||
ACE4_DIRECTORY_INHERIT_ACE. If the server does not | ACE4_DIRECTORY_INHERIT_ACE. If the server does not | |||
support any form of ACL inheritance, the server should | support any form of ACL inheritance, the server should | |||
reject the request with NFS4ERR_ATTRNOTSUPP. If the | reject the request with NFS4ERR_ATTRNOTSUPP. If the | |||
server supports a single "inherit ACE" flag that | server supports a single "inherit ACE" flag that | |||
applies to both files and directories, the server may | applies to both files and directories, the server may | |||
reject the request (i.e., requiring the client to set | reject the request (i.e., requiring the client to set | |||
both the file and directory inheritance flags). The | both the file and directory inheritance flags). The | |||
server may also accept the request and silently turn | server may also accept the request and silently turn | |||
on the ACE4_DIRECTORY_INHERIT_ACE flag. | on the ACE4_DIRECTORY_INHERIT_ACE flag. | |||
</t> | </t> | |||
<section title="Discussion of Flag Bits"> | <section numbered="true" toc="default"> | |||
<name>Discussion of Flag Bits</name> | ||||
<t> | <dl newline="true" spacing="normal"> | |||
<list style="hanging"> | <dt>ACE4_FILE_INHERIT_ACE</dt> | |||
<t hangText="ACE4_FILE_INHERIT_ACE"> | <dd> | |||
<vspace /> | ||||
Any non-directory file in any | Any non-directory file in any | |||
sub-directory will get this ACE | sub-directory will get this ACE | |||
inherited. | inherited. | |||
</t> | </dd> | |||
<dt>ACE4_DIRECTORY_INHERIT_ACE</dt> | ||||
<t hangText="ACE4_DIRECTORY_INHERIT_ACE"> | <dd> | |||
<vspace /> | <t> | |||
Can be placed on a directory and indicates | Can be placed on a directory and indicates | |||
that this ACE should be added to each new | that this ACE should be added to each new | |||
directory created. | directory created. | |||
<vspace /> | </t> | |||
<t> | ||||
If this flag is set in an ACE in an ACL | If this flag is set in an ACE in an ACL | |||
attribute to be set on a non-directory | attribute to be set on a non-directory | |||
file system object, the operation | file system object, the operation | |||
attempting to set the ACL SHOULD fail | attempting to set the ACL <bcp14>SHOULD</bcp14> fail | |||
with NFS4ERR_ATTRNOTSUPP. | with NFS4ERR_ATTRNOTSUPP. | |||
</t> | </t> | |||
</dd> | ||||
<t hangText="ACE4_NO_PROPAGATE_INHERIT_ACE"> | <dt>ACE4_NO_PROPAGATE_INHERIT_ACE</dt> | |||
<vspace /> | <dd> | |||
Can be placed on a directory. This flag | Can be placed on a directory. This flag | |||
tells the server that inheritance of this | tells the server that inheritance of this | |||
ACE should stop at newly created child | ACE should stop at newly created child | |||
directories. | directories. | |||
</t> | </dd> | |||
<dt>ACE4_INHERIT_ONLY_ACE</dt> | ||||
<t hangText="ACE4_INHERIT_ONLY_ACE"> | <dd> | |||
<vspace /> | <t> | |||
Can be placed on a directory but does not | Can be placed on a directory but does not | |||
apply to the directory; ALLOW and DENY ACEs | apply to the directory; ALLOW and DENY ACEs | |||
with this bit set do not affect access to | with this bit set do not affect access to | |||
the directory, and AUDIT and ALARM ACEs | the directory, and AUDIT and ALARM ACEs | |||
with this bit set do not trigger log or | with this bit set do not trigger log or | |||
alarm events. Such ACEs only take effect | alarm events. Such ACEs only take effect | |||
once they are applied (with this bit | once they are applied (with this bit | |||
cleared) to newly created files and | cleared) to newly created files and | |||
directories as specified by the | directories as specified by the | |||
ACE4_FILE_INHERIT_ACE and ACE4_DIRECTORY_INHERIT_ACE | ACE4_FILE_INHERIT_ACE and ACE4_DIRECTORY_INHERIT_ACE | |||
flags. | flags. | |||
<vspace blankLines="1"/> | </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 SHOULD fail with | attribute <bcp14>SHOULD</bcp14> fail with | |||
NFS4ERR_ATTRNOTSUPP. | NFS4ERR_ATTRNOTSUPP. | |||
</t> | </t> | |||
</dd> | ||||
<t hangText="ACE4_SUCCESSFUL_ACCESS_ACE_FLAG"> | <dt>ACE4_SUCCESSFUL_ACCESS_ACE_FLAG and | |||
<vspace /> | ACE4_FAILED_ACCESS_ACE_FLAG</dt> | |||
</t> | <dd> | |||
<t hangText="ACE4_FAILED_ACCESS_ACE_FLAG"> | <t> | |||
<vspace /> | ||||
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 9292 ¶ | 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. | |||
</t> | </t> | |||
<t> | ||||
<t hangText=""> | ||||
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> | |||
</t> | </dd> | |||
<dt>ACE4_IDENTIFIER_GROUP</dt> | ||||
<t hangText="ACE4_IDENTIFIER_GROUP"> | <dd> | |||
<vspace /> | ||||
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 MUST 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 | |||
<xref target="acewho" />. | <xref target="acewho" format="default"/>. | |||
</t> | </dd> | |||
<dt>ACE4_INHERITED_ACE</dt> | ||||
<t hangText="ACE4_INHERITED_ACE"> | <dd> | |||
<vspace /> | ||||
Indicates that this ACE is inherited from | Indicates that this ACE is inherited from | |||
a parent directory. A server that supports | a parent directory. A server that supports | |||
automatic inheritance will place | automatic inheritance will place | |||
this flag on any ACEs inherited from the | this flag on any ACEs inherited from the | |||
parent directory when creating a new | parent directory when creating a new | |||
object. Client applications will use this | object. Client applications will use this | |||
to perform automatic inheritance. | to perform automatic inheritance. | |||
Clients and servers MUST clear this | Clients and servers <bcp14>MUST</bcp14> clear this | |||
bit in the acl attribute; it may only | bit in the acl attribute; it may only | |||
be used in the dacl and sacl attributes. | be used in the dacl and sacl attributes. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="acewho" numbered="true" toc="default"> | |||
<section title="ACE Who" anchor="acewho"> | <name>ACE Who</name> | |||
<t> | <t> | |||
The "who" field of an ACE is an identifier that | The "who" field of an ACE is an identifier that | |||
specifies the principal or principals to whom the ACE | specifies the principal or principals to whom the ACE | |||
applies. It may refer to a user or a group, with the flag | applies. It may refer to a user or a group, with the flag | |||
bit ACE4_IDENTIFIER_GROUP specifying which. | bit ACE4_IDENTIFIER_GROUP specifying which. | |||
</t> | </t> | |||
<t> | <t> | |||
There are several special identifiers that need to be | There are several special identifiers that need to be | |||
understood universally, rather than in the context of a | understood universally, rather than in the context of a | |||
particular DNS domain. Some of these identifiers cannot be | particular DNS domain. Some of these identifiers cannot be | |||
understood when an NFS client accesses the server, but | understood when an NFS client accesses the server, but | |||
have meaning when a local process accesses the file. The | have meaning when a local process accesses the file. The | |||
ability to display and modify these permissions is | ability to display and modify these permissions is | |||
permitted over NFS, even if none of the access methods on | permitted over NFS, even if none of the access methods on | |||
the server understands the identifiers. | the server understands the identifiers. | |||
</t> | </t> | |||
<texttable anchor="specialwho"> | <table anchor="specialwho" align="center"> | |||
<ttcol>Who</ttcol> | <thead> | |||
<ttcol>Description</ttcol> | <tr> | |||
<c>OWNER</c> | <th align="left">Who</th> | |||
<c> | <th align="left">Description</th> | |||
</tr> | ||||
</thead> | ||||
<tbody> | ||||
<tr> | ||||
<td align="left">OWNER</td> | ||||
<td align="left"> | ||||
The owner of the file. | The owner of the file. | |||
</c> | </td> | |||
<c>GROUP</c> | </tr> | |||
<c> | <tr> | |||
<td align="left">GROUP</td> | ||||
<td align="left"> | ||||
The group associated with the file. | The group associated with the file. | |||
</c> | </td> | |||
<c>EVERYONE</c> | </tr> | |||
<c> | <tr> | |||
<td align="left">EVERYONE</td> | ||||
<td align="left"> | ||||
The world, including the owner and owning group. | The world, including the owner and owning group. | |||
</c> | </td> | |||
<c>INTERACTIVE</c> | </tr> | |||
<c> | <tr> | |||
<td align="left">INTERACTIVE</td> | ||||
<td align="left"> | ||||
Accessed from an interactive terminal. | Accessed from an interactive terminal. | |||
</c> | </td> | |||
<c>NETWORK</c> | </tr> | |||
<c> | <tr> | |||
<td align="left">NETWORK</td> | ||||
<td align="left"> | ||||
Accessed via the network. | Accessed via the network. | |||
</c> | </td> | |||
<c>DIALUP</c> | </tr> | |||
<c> | <tr> | |||
<td align="left">DIALUP</td> | ||||
<td align="left"> | ||||
Accessed as a dialup user to the server. | Accessed as a dialup user to the server. | |||
</c> | </td> | |||
<c>BATCH</c> | </tr> | |||
<c> | <tr> | |||
<td align="left">BATCH</td> | ||||
<td align="left"> | ||||
Accessed from a batch job. | Accessed from a batch job. | |||
</c> | </td> | |||
<c>ANONYMOUS</c> | </tr> | |||
<c> | <tr> | |||
<td align="left">ANONYMOUS</td> | ||||
<td align="left"> | ||||
Accessed without any authentication. | Accessed without any authentication. | |||
</c> | </td> | |||
<c>AUTHENTICATED</c> | </tr> | |||
<c> | <tr> | |||
<td align="left">AUTHENTICATED</td> | ||||
<td align="left"> | ||||
Any authenticated user (opposite of | Any authenticated user (opposite of | |||
ANONYMOUS). | ANONYMOUS). | |||
</c> | </td> | |||
<c>SERVICE</c> | </tr> | |||
<c> | <tr> | |||
<td align="left">SERVICE</td> | ||||
<td align="left"> | ||||
Access from a system service. | Access from a system service. | |||
</c> | </td> | |||
</texttable> | </tr> | |||
<t> | </tbody> | |||
</table> | ||||
<t> | ||||
To avoid conflict, these special identifiers are | To avoid conflict, these special identifiers are | |||
distinguished by an appended "@" and should appear in the | distinguished by an appended "@" and should appear in the | |||
form "xxxx@" (with no domain name after the "@"), for | form "xxxx@" (with no domain name after the "@"), for | |||
example, ANONYMOUS@. | example, ANONYMOUS@. | |||
</t> | </t> | |||
<t> | <t> | |||
The ACE4_IDENTIFIER_GROUP flag MUST be ignored on | The ACE4_IDENTIFIER_GROUP flag <bcp14>MUST</bcp14> be ignored on | |||
entries with these special identifiers. When encoding | entries with these special identifiers. When encoding | |||
entries with these special identifiers, the | entries with these special identifiers, the | |||
ACE4_IDENTIFIER_GROUP flag SHOULD be set to zero. | ACE4_IDENTIFIER_GROUP flag <bcp14>SHOULD</bcp14> be set to zero. | |||
</t> | </t> | |||
<section numbered="true" toc="default"> | ||||
<section title="Discussion of EVERYONE@"> | <name>Discussion of EVERYONE@</name> | |||
<t> | <t> | |||
It is important to note that "EVERYONE@" is not | It is important to note that "EVERYONE@" is not | |||
equivalent to the UNIX "other" entity. This is | equivalent to the UNIX "other" entity. This is | |||
because, by definition, UNIX "other" does not include | because, by definition, UNIX "other" does not include | |||
the owner or owning group of a file. "EVERYONE@" means | the owner or owning group of a file. "EVERYONE@" means | |||
literally everyone, including the owner or owning | literally everyone, including the owner or owning | |||
group. | group. | |||
</t> | </t> | |||
</section> | ||||
</section> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="attrdef_dacl" numbered="true" toc="default"> | |||
<section anchor="attrdef_dacl" | <name>Attribute 58: dacl</name> | |||
title="Attribute 58: dacl"> | <t> | |||
<t> | ||||
The dacl attribute is like the acl attribute, | The dacl attribute is like the acl attribute, | |||
but dacl allows | but dacl allows | |||
just ALLOW and DENY ACEs. The dacl | just ALLOW and DENY ACEs. The dacl | |||
attribute supports automatic inheritance (see | attribute supports automatic inheritance (see | |||
<xref target="auto_inherit" />). | <xref target="auto_inherit" format="default"/>). | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="attrdef_sacl" numbered="true" toc="default"> | ||||
<section anchor="attrdef_sacl" | <name>Attribute 59: sacl</name> | |||
title="Attribute 59: sacl"> | <t> | |||
<t> | ||||
The sacl attribute is like the acl attribute, | The sacl attribute is like the acl attribute, | |||
but sacl allows | but sacl allows | |||
just AUDIT and ALARM ACEs. The sacl | just AUDIT and ALARM ACEs. The sacl | |||
attribute supports automatic inheritance (see | attribute supports automatic inheritance (see | |||
<xref target="auto_inherit" />). | <xref target="auto_inherit" format="default"/>). | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="attrdef_mode" numbered="true" toc="default"> | ||||
<section anchor="attrdef_mode" | <name>Attribute 33: mode</name> | |||
title="Attribute 33: mode"> | <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="xdr"><![CDATA[ | ||||
<figure> | ||||
<artwork> | ||||
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 */ | |||
const MODE4_WOTH = 0x002; /* write permission: other */ | const MODE4_WOTH = 0x002; /* write permission: other */ | |||
const MODE4_XOTH = 0x001; /* execute permission: other */ | const MODE4_XOTH = 0x001; /* execute permission: other */ | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
<t> | ||||
Bits MODE4_RUSR, MODE4_WUSR, and MODE4_XUSR apply to the | Bits MODE4_RUSR, MODE4_WUSR, and MODE4_XUSR apply to the | |||
principal identified in the owner attribute. Bits MODE4_RGRP, | principal identified in the owner attribute. Bits MODE4_RGRP, | |||
MODE4_WGRP, and MODE4_XGRP apply to principals identified in | MODE4_WGRP, and MODE4_XGRP apply to principals identified in | |||
the owner_group attribute but who are not identified in the | the owner_group attribute but who are not identified in the | |||
owner attribute. Bits MODE4_ROTH, MODE4_WOTH, and MODE4_XOTH apply | owner attribute. Bits MODE4_ROTH, MODE4_WOTH, and MODE4_XOTH apply | |||
to any principal that does not match that in the owner | to any principal that does not match that in the owner | |||
attribute and does not have a group matching that of the | attribute and does not have a group matching that of the | |||
owner_group attribute. | owner_group attribute. | |||
</t> | </t> | |||
<t> | <t> | |||
Bits within a mode other than those specified above | Bits within a mode other than those specified above | |||
are not defined by this protocol. A server | are not defined by this protocol. A server | |||
MUST NOT return bits other than those defined above in a | <bcp14>MUST NOT</bcp14> return bits other than those defined above in | |||
GETATTR or READDIR operation, and it MUST return NFS4ERR_INVAL | a | |||
GETATTR or READDIR operation, and it <bcp14>MUST</bcp14> return NFS4ER | ||||
R_INVAL | ||||
if bits other than those defined above are set in a SETATTR, | if bits other than those defined above are set in a SETATTR, | |||
CREATE, OPEN, VERIFY, or NVERIFY operation. | CREATE, OPEN, VERIFY, or NVERIFY operation. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="attrdef_mode_set_masked" | <section anchor="attrdef_mode_set_masked" numbered="true" toc="default"> | |||
title="Attribute 74: mode_set_masked"> | <name>Attribute 74: mode_set_masked</name> | |||
<t> | <t> | |||
The mode_set_masked attribute is a write-only attribute | The mode_set_masked attribute is a write-only attribute | |||
that allows individual bits in the mode attribute to be | that allows individual bits in the mode attribute to be | |||
set or reset, without changing others. It allows, for | set or reset, without changing others. It allows, for | |||
example, the bits MODE4_SUID, MODE4_SGID, and MODE4_SVTX | example, the bits MODE4_SUID, MODE4_SGID, and MODE4_SVTX | |||
to be modified while leaving unmodified any of the | to be modified while leaving unmodified any of the | |||
nine low-order mode bits devoted to permissions. | nine low-order mode bits devoted to permissions. | |||
</t> | </t> | |||
<t> | <t> | |||
In such instances that the nine low-order bits are left | In such instances that the nine low-order bits are left | |||
unmodified, then neither the acl nor the dacl attribute | unmodified, then neither the acl nor the dacl attribute | |||
should be automatically modified as discussed in | should be automatically modified as discussed in | |||
<xref target="setattr" />. | <xref target="setattr" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
The mode_set_masked attribute consists of two words, | The mode_set_masked attribute consists of two words, | |||
each in the form of a mode4. The first consists of the | each in the form of a mode4. The first consists of the | |||
value to be applied to the current mode value and the | value to be applied to the current mode value and the | |||
second is a mask. Only bits set to one in the mask word | second is a mask. Only bits set to one in the mask word | |||
are changed (set or reset) in the file's mode. All | are changed (set or reset) in the file's mode. All | |||
other bits in the mode remain unchanged. Bits in the | other bits in the mode remain unchanged. Bits in the | |||
first word that correspond to bits that are zero in | first word that correspond to bits that are zero in | |||
the mask are ignored, except that undefined bits are | the mask are ignored, except that undefined bits are | |||
checked for validity and can result in NFS4ERR_INVAL as | checked for validity and can result in NFS4ERR_INVAL as | |||
described below. | described below. | |||
</t> | </t> | |||
<t> | <t> | |||
The mode_set_masked attribute is only valid in a SETATTR | The mode_set_masked attribute is only valid in a SETATTR | |||
operation. If it is used in a CREATE or OPEN operation, the | operation. If it is used in a CREATE or OPEN operation, the | |||
server MUST return NFS4ERR_INVAL. | server <bcp14>MUST</bcp14> return NFS4ERR_INVAL. | |||
</t> | </t> | |||
<t> | <t> | |||
Bits not defined as valid in the mode attribute are not | Bits not defined as valid in the mode attribute are not | |||
valid in either word of the mode_set_masked attribute. | valid in either word of the mode_set_masked attribute. | |||
The server MUST return NFS4ERR_INVAL | The server <bcp14>MUST</bcp14> return NFS4ERR_INVAL | |||
if any such bits are set to one in a SETATTR. | if any such bits are set to one in a SETATTR. | |||
If the mode and | If the mode and | |||
mode_set_masked attributes are both specified in the | mode_set_masked attributes are both specified in the | |||
same SETATTR, the server MUST also return NFS4ERR_INVAL. | same SETATTR, the server <bcp14>MUST</bcp14> also return NFS4ERR_INVAL | |||
</t> | . | |||
</t> | ||||
</section> | ||||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
</section> | <name>Common Methods</name> | |||
<t> | ||||
<section title="Common Methods"> | ||||
<t> | ||||
The requirements in this section will be referred to in future | The requirements in this section will be referred to in future | |||
sections, especially <xref target="aclreqs" />. | sections, especially <xref target="aclreqs" format="default"/>. | |||
</t> | </t> | |||
<section title="Interpreting an ACL" anchor="useacl"> | <section anchor="useacl" numbered="true" toc="default"> | |||
<section title="Server Considerations" anchor="serverinterp"> | <name>Interpreting an ACL</name> | |||
<t> | <section anchor="serverinterp" numbered="true" toc="default"> | |||
<name>Server Considerations</name> | ||||
<t> | ||||
The server uses the algorithm described in | The server uses the algorithm described in | |||
<xref target="attrdef_acl"/> to determine whether an ACL | <xref target="attrdef_acl" format="default"/> to determine whether an ACL | |||
allows access to an object. However, the ACL might not be | allows access to an object. However, the ACL might not be | |||
the sole determiner of access. For example: | the sole determiner of access. For example: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
In the case of a file system exported as read-only, | In the case of a file system exported as read-only, | |||
the server may deny write access even though | the server may deny write access even though | |||
an object's ACL grants it. | an object's ACL grants it. | |||
</t> | </li> | |||
<li> | ||||
<t> | Server implementations <bcp14>MAY</bcp14> grant ACE4_WRITE_ACL | |||
Server implementations MAY grant ACE4_WRITE_ACL | ||||
and ACE4_READ_ACL permissions to prevent | and ACE4_READ_ACL permissions to prevent | |||
a situation from arising in which there is no valid | a situation from arising in which there is no valid | |||
way to ever modify the ACL. | way to ever modify the ACL. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
All servers will allow a user the ability to read | All servers will allow a user the ability to read | |||
the data of the file when only the execute | the data of the file when only the execute | |||
permission is granted (i.e., if the ACL denies the | permission is granted (i.e., if the ACL denies the | |||
user the ACE4_READ_DATA access and allows the user | user the ACE4_READ_DATA access and allows the user | |||
ACE4_EXECUTE, the server will allow the user to | ACE4_EXECUTE, the server will allow the user to | |||
read the data of the file). | read the data of the file). | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
Many servers have the notion of owner-override in | Many servers have the notion of owner-override in | |||
which the owner of the object is allowed to | which the owner of the object is allowed to | |||
override accesses that are denied by the ACL. | override accesses that are denied by the ACL. | |||
This may be helpful, for example, to allow users | This may be helpful, for example, to allow users | |||
continued access to open files on which the | continued access to open files on which the | |||
permissions have changed. | permissions have changed. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
Many servers have the notion of a | Many servers have the notion of a | |||
"superuser" that has privileges beyond | "superuser" that has privileges beyond | |||
an ordinary user. The superuser may be able | an ordinary user. The superuser may be able | |||
to read or write data or metadata in ways that would | to read or write data or metadata in ways that would | |||
not be permitted by the ACL. | not be permitted by the ACL. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
A retention attribute might also block access otherwise | A retention attribute might also block access otherwise | |||
allowed by ACLs (see <xref target="retention"/>). | allowed by ACLs (see <xref target="retention" format="default"/> | |||
</t> | ). | |||
</li> | ||||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section anchor="clientinterp" numbered="true" toc="default"> | |||
<name>Client Considerations</name> | ||||
<section title="Client Considerations" anchor="clientinterp"> | <t> | |||
<t> | Clients <bcp14>SHOULD NOT</bcp14> do their own access checks based o | |||
Clients SHOULD NOT do their own access checks based on | n | |||
their interpretation of the ACL, but rather use the OPEN and | their interpretation of the ACL, but rather use the OPEN and | |||
ACCESS operations to do access checks. This allows the | ACCESS operations to do access checks. This allows the | |||
client to act on the results of having the server | client to act on the results of having the server | |||
determine whether or not access should be granted based on | determine whether or not access should be granted based on | |||
its interpretation of the ACL. | its interpretation of the ACL. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
Clients must be aware of situations in which an object's | Clients must be aware of situations in which an object's | |||
ACL will define a certain access even though the server | ACL will define a certain access even though the server | |||
will not enforce it. In general, but especially in these | will not enforce it. In general, but especially in these | |||
situations, the client needs to do its part in the | situations, the client needs to do its part in the | |||
enforcement of access as defined by the ACL. To do this, | enforcement of access as defined by the ACL. To do this, | |||
the client MAY send the appropriate ACCESS operation | the client <bcp14>MAY</bcp14> send the appropriate ACCESS operation | |||
prior to servicing the request of the user or application | prior to servicing the request of the user or application | |||
in order to determine whether the user or application | in order to determine whether the user or application | |||
should be granted the access requested. For examples in | should be granted the access requested. For examples in | |||
which the ACL may define accesses that the server doesn't | which the ACL may define accesses that the server doesn't | |||
enforce, see <xref target="serverinterp"/>. | enforce, see <xref target="serverinterp" format="default"/>. | |||
</t> | </t> | |||
</section> | ||||
</section> | </section> | |||
</section> | <section anchor="computemode" numbered="true" toc="default"> | |||
<name>Computing a Mode Attribute from an ACL</name> | ||||
<section title="Computing a Mode Attribute from an ACL" | <t> | |||
anchor="computemode"> | ||||
<t> | ||||
The following method can be used to calculate the MODE4_R*, | The following method can be used to calculate the MODE4_R*, | |||
MODE4_W*, and MODE4_X* bits of a mode attribute, based upon | MODE4_W*, and MODE4_X* bits of a mode attribute, based upon | |||
an ACL. | an ACL. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
First, for each of the special identifiers OWNER@, GROUP@, and | First, for each of the special identifiers OWNER@, GROUP@, and | |||
EVERYONE@, evaluate the ACL in order, considering only ALLOW | EVERYONE@, evaluate the ACL in order, considering only ALLOW | |||
and DENY ACEs for the identifier EVERYONE@ and for the | and DENY ACEs for the identifier EVERYONE@ and for the | |||
identifier under consideration. The result of the evaluation | identifier under consideration. The result of the evaluation | |||
will be an NFSv4 ACL mask showing exactly which bits are | will be an NFSv4 ACL mask showing exactly which bits are | |||
permitted to that identifier. | permitted to that identifier. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
Then translate the calculated mask for OWNER@, GROUP@, and | Then translate the calculated mask for OWNER@, GROUP@, and | |||
EVERYONE@ into mode bits for, respectively, the user, group, | EVERYONE@ into mode bits for, respectively, the user, group, | |||
and other, as follows: | and other, as follows: | |||
<list style="numbers"> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
Set the read bit (MODE4_RUSR, MODE4_RGRP, or | Set the read bit (MODE4_RUSR, MODE4_RGRP, or | |||
MODE4_ROTH) if and only if ACE4_READ_DATA is set in | MODE4_ROTH) if and only if ACE4_READ_DATA is set in | |||
the corresponding mask. | the corresponding mask. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
Set the write bit (MODE4_WUSR, MODE4_WGRP, or | Set the write bit (MODE4_WUSR, MODE4_WGRP, or | |||
MODE4_WOTH) if and only if ACE4_WRITE_DATA and | MODE4_WOTH) if and only if ACE4_WRITE_DATA and | |||
ACE4_APPEND_DATA are both set in the corresponding | ACE4_APPEND_DATA are both set in the corresponding | |||
mask. | mask. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
Set the execute bit (MODE4_XUSR, MODE4_XGRP, or | Set the execute bit (MODE4_XUSR, MODE4_XGRP, or | |||
MODE4_XOTH), if and only if ACE4_EXECUTE is set in the | MODE4_XOTH), if and only if ACE4_EXECUTE is set in the | |||
corresponding mask. | corresponding mask. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | <section numbered="true" toc="default"> | |||
<section title="Discussion"> | <name>Discussion</name> | |||
<t> | <t> | |||
Some server implementations also add bits permitted to | Some server implementations also add bits permitted to | |||
named users and groups to the group bits (MODE4_RGRP, | named users and groups to the group bits (MODE4_RGRP, | |||
MODE4_WGRP, and MODE4_XGRP). | MODE4_WGRP, and MODE4_XGRP). | |||
</t> | </t> | |||
<t> | <t> | |||
Implementations are discouraged from doing this, because | Implementations are discouraged from doing this, because | |||
it has been found to cause confusion for users who see | it has been found to cause confusion for users who see | |||
members of a file's group denied access that the mode | members of a file's group denied access that the mode | |||
bits appear to allow. (The presence of DENY ACEs may also | bits appear to allow. (The presence of DENY ACEs may also | |||
lead to such behavior, but DENY ACEs are expected to be | lead to such behavior, but DENY ACEs are expected to be | |||
more rarely used.) | more rarely used.) | |||
</t> | </t> | |||
<t> | <t> | |||
The same user confusion seen when fetching the mode also | The same user confusion seen when fetching the mode also | |||
results if setting the mode does not effectively control | results if setting the mode does not effectively control | |||
permissions for the owner, group, and other users; this | permissions for the owner, group, and other users; this | |||
motivates some of the requirements that follow. | motivates some of the requirements that follow. | |||
</t> | </t> | |||
</section> | ||||
</section> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="aclreqs" numbered="true" toc="default"> | |||
<name>Requirements</name> | ||||
<section title="Requirements" anchor="aclreqs"> | <t> | |||
<t> | ||||
The server that supports both mode and ACL must take care to | The server that supports both mode and ACL must take care to | |||
synchronize the MODE4_*USR, MODE4_*GRP, and MODE4_*OTH bits with | synchronize the MODE4_*USR, MODE4_*GRP, and MODE4_*OTH bits with | |||
the ACEs that have respective who fields of "OWNER@", "GROUP@", | the ACEs that have respective who fields of "OWNER@", "GROUP@", | |||
and "EVERYONE@". This way, the client can see if semantically equivalent | and "EVERYONE@". This way, the client can see if semantically equivalent | |||
access permissions exist whether the client asks for the owner, | access permissions exist whether the client asks for the owner, | |||
owner_group, and mode attributes or for just the ACL. | owner_group, and mode attributes or for just the ACL. | |||
</t> | </t> | |||
<t> | <t> | |||
In this section, much is made of the methods in <xref | In this section, much is made of the methods in <xref target="computemod | |||
target="computemode" / | e" format="default"/>. Many requirements refer to this section. | |||
>. Many requirements refer to this section. | ||||
But note that the methods have behaviors specified with | But note that the methods have behaviors specified with | |||
"SHOULD". This is intentional, to avoid invalidating | "<bcp14>SHOULD</bcp14>". This is intentional, to avoid invalidating | |||
existing implementations that compute the mode according to the | existing implementations that compute the mode according to the | |||
withdrawn POSIX ACL draft (1003.1e draft 17), rather than by | withdrawn POSIX ACL draft (1003.1e draft 17), rather than by | |||
actual permissions on owner, group, and other. | actual permissions on owner, group, and other. | |||
</t> | </t> | |||
<section title="Setting the Mode and/or ACL Attributes" | <section anchor="setattr" numbered="true" toc="default"> | |||
anchor="setattr"> | <name>Setting the Mode and/or ACL Attributes</name> | |||
<t> | <t> | |||
In the case where a server supports the sacl or | In the case where a server supports the sacl or | |||
dacl attribute, in addition to the acl attribute, | dacl attribute, in addition to the acl attribute, | |||
the server MUST fail a request to set the acl | the server <bcp14>MUST</bcp14> fail a request to set the acl | |||
attribute simultaneously with a dacl or sacl | attribute simultaneously with a dacl or sacl | |||
attribute. The error to be given is NFS4ERR_ATTRNOTSUPP. | attribute. The error to be given is NFS4ERR_ATTRNOTSUPP. | |||
</t> | </t> | |||
<section title="Setting Mode and not ACL" anchor="setmode"> | <section anchor="setmode" numbered="true" toc="default"> | |||
<t> | <name>Setting Mode and not ACL</name> | |||
<t> | ||||
When any of the nine low-order mode bits | When any of the nine low-order mode bits | |||
are subject to change, either because the mode | are subject to change, either because the mode | |||
attribute was set or because the mode_set_masked | attribute was set or because the mode_set_masked | |||
attribute was set and the mask included one or more | attribute was set and the mask included one or more | |||
bits from the nine low-order mode bits, | bits from the nine low-order mode bits, | |||
and no ACL attribute is explicitly | and no ACL attribute is explicitly | |||
set, the acl and dacl attributes must be modified | set, the acl and dacl attributes must be modified | |||
in accordance with the updated value of those bits. | in accordance with the updated value of those bits. | |||
This must happen | This must happen | |||
even if the value of the low-order bits | even if the value of the low-order bits | |||
is the same after the mode is set as before. | is the same after the mode is set as before. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that any AUDIT or ALARM ACEs (hence any ACEs in the | Note that any AUDIT or ALARM ACEs (hence any ACEs in the | |||
sacl attribute) are unaffected by changes to the mode. | sacl attribute) are unaffected by changes to the mode. | |||
</t> | </t> | |||
<t> | <t> | |||
In cases in which the permissions bits are subject to | In cases in which the permissions bits are subject to | |||
change, the acl and dacl attributes | change, the acl and dacl attributes | |||
MUST be modified such that the mode computed via the | <bcp14>MUST</bcp14> be modified such that the mode computed via the | |||
method in | method in | |||
<xref target="computemode" /> | <xref target="computemode" format="default"/> | |||
yields the low-order nine bits (MODE4_R*, MODE4_W*, | yields the low-order nine bits (MODE4_R*, MODE4_W*, | |||
MODE4_X*) of the mode attribute as modified by the | MODE4_X*) of the mode attribute as modified by the | |||
attribute change. The ACL attributes | attribute change. The ACL attributes | |||
SHOULD also be modified such that: | <bcp14>SHOULD</bcp14> also be modified such that: | |||
<list style="numbers"> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
If MODE4_RGRP is not set, entities explicitly | If MODE4_RGRP is not set, entities explicitly | |||
listed in the ACL other than OWNER@ and EVERYONE@ | listed in the ACL other than OWNER@ and EVERYONE@ | |||
SHOULD NOT be granted ACE4_READ_DATA. | <bcp14>SHOULD NOT</bcp14> be granted ACE4_READ_DATA. | |||
</t> | </li> | |||
<t> | <li> | |||
If MODE4_WGRP is not set, entities explicitly | If MODE4_WGRP is not set, entities explicitly | |||
listed in the ACL other than OWNER@ and | listed in the ACL other than OWNER@ and | |||
EVERYONE@ SHOULD NOT be granted | EVERYONE@ <bcp14>SHOULD NOT</bcp14> be granted | |||
ACE4_WRITE_DATA or ACE4_APPEND_DATA. | ACE4_WRITE_DATA or ACE4_APPEND_DATA. | |||
</t> | </li> | |||
<t> | <li> | |||
If MODE4_XGRP is not set, entities explicitly | If MODE4_XGRP is not set, entities explicitly | |||
listed in the ACL other than OWNER@ and EVERYONE@ | listed in the ACL other than OWNER@ and EVERYONE@ | |||
SHOULD NOT be granted ACE4_EXECUTE. | <bcp14>SHOULD NOT</bcp14> be granted ACE4_EXECUTE. | |||
</t> | </li> | |||
</list> | </ol> | |||
<t> | ||||
Access mask bits other than those listed above, appearing | Access mask bits other than those listed above, appearing | |||
in ALLOW ACEs, MAY also be disabled. | in ALLOW ACEs, <bcp14>MAY</bcp14> also be disabled. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that ACEs with the flag ACE4_INHERIT_ONLY_ACE set do | Note that ACEs with the flag ACE4_INHERIT_ONLY_ACE set do | |||
not affect the permissions of the ACL itself, nor do ACEs | not affect the permissions of the ACL itself, nor do ACEs | |||
of the type AUDIT and ALARM. As such, it is desirable to | of the type AUDIT and ALARM. As such, it is desirable to | |||
leave these ACEs unmodified when modifying the ACL | leave these ACEs unmodified when modifying the ACL | |||
attributes. | attributes. | |||
</t> | </t> | |||
<t> | <t> | |||
Also note that the requirement may be met by | Also note that the requirement may be met by | |||
discarding the acl and dacl, in favor of an ACL | discarding the acl and dacl, in favor of an ACL | |||
that represents the mode and only the mode. This is | that represents the mode and only the mode. This is | |||
permitted, but it is preferable for a server to | permitted, but it is preferable for a server to | |||
preserve as much of the ACL as possible without | preserve as much of the ACL as possible without | |||
violating the above requirements. Discarding the | violating the above requirements. Discarding the | |||
ACL makes it effectively impossible for a file | ACL makes it effectively impossible for a file | |||
created with a mode attribute to inherit an ACL | created with a mode attribute to inherit an ACL | |||
(see <xref target="aclcreate" />). | (see <xref target="aclcreate" format="default"/>). | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Setting ACL and Not Mode" | <section anchor="settingacl" numbered="true" toc="default"> | |||
anchor="settingacl"> | <name>Setting ACL and Not Mode</name> | |||
<t> | <t> | |||
When setting the acl or dacl and not setting the | When setting the acl or dacl and not setting the | |||
mode or mode_set_masked attributes, the permission | mode or mode_set_masked attributes, the permission | |||
bits of the mode need to be derived from the ACL. | bits of the mode need to be derived from the ACL. | |||
In this case, the ACL attribute SHOULD be set as | In this case, the ACL attribute <bcp14>SHOULD</bcp14> be set as | |||
given. The nine low-order bits of the mode | given. The nine low-order bits of the mode | |||
attribute (MODE4_R*, MODE4_W*, MODE4_X*) MUST be | attribute (MODE4_R*, MODE4_W*, MODE4_X*) <bcp14>MUST</bcp14> be | |||
modified to match the result of the method in | modified to match the result of the method in | |||
<xref target="computemode" />. The three high-order bits | <xref target="computemode" format="default"/>. The three high-order b its | |||
of the mode (MODE4_SUID, MODE4_SGID, MODE4_SVTX) | of the mode (MODE4_SUID, MODE4_SGID, MODE4_SVTX) | |||
SHOULD remain unchanged. | <bcp14>SHOULD</bcp14> remain unchanged. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Setting Both ACL and Mode" anchor="setboth"> | <section anchor="setboth" numbered="true" toc="default"> | |||
<t> | <name>Setting Both ACL and Mode</name> | |||
<t> | ||||
When setting both the mode (includes use of either the | When setting both the mode (includes use of either the | |||
mode attribute or the mode_set_masked attribute) | mode attribute or the mode_set_masked attribute) | |||
and the acl or dacl attributes in the | and the acl or dacl attributes in the | |||
same operation, the attributes MUST be applied in this | same operation, the attributes <bcp14>MUST</bcp14> be applied in thi s | |||
order: mode (or mode_set_masked), then ACL. The | order: mode (or mode_set_masked), then ACL. The | |||
mode-related attribute is set as given, | mode-related attribute is set as given, | |||
then the ACL attribute is set as given, possibly changing | then the ACL attribute is set as given, possibly changing | |||
the final mode, as described above in | the final mode, as described above in | |||
<xref target="settingacl" />. | <xref target="settingacl" format="default"/>. | |||
</t> | </t> | |||
</section> | ||||
</section> | </section> | |||
</section> | <section numbered="true" toc="default"> | |||
<section title="Retrieving the Mode and/or ACL Attributes"> | <name>Retrieving the Mode and/or ACL Attributes</name> | |||
<t> | <t> | |||
This section applies only to servers that support both the | This section applies only to servers that support both the | |||
mode and ACL attributes. | mode and ACL attributes. | |||
</t> | </t> | |||
<t> | <t> | |||
Some server implementations may have a concept of | Some server implementations may have a concept of | |||
"objects without ACLs", meaning that all permissions | "objects without ACLs", meaning that all permissions | |||
are granted and denied according to the mode attribute and | are granted and denied according to the mode attribute and | |||
that no ACL attribute is stored for that object. If an ACL | that no ACL attribute is stored for that object. If an ACL | |||
attribute is requested of such a server, the server SHOULD | attribute is requested of such a server, the server <bcp14>SHOULD</bcp 14> | |||
return an ACL that does not conflict with the mode; that is to | return an ACL that does not conflict with the mode; that is to | |||
say, the ACL returned SHOULD represent the nine low-order bits | say, the ACL returned <bcp14>SHOULD</bcp14> represent the nine low-ord er bits | |||
of the mode attribute (MODE4_R*, MODE4_W*, MODE4_X*) as | of the mode attribute (MODE4_R*, MODE4_W*, MODE4_X*) as | |||
described in <xref target="computemode" />. | described in <xref target="computemode" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
For other server implementations, the ACL attribute is always | For other server implementations, the ACL attribute is always | |||
present for every object. Such servers SHOULD store at least | present for every object. Such servers <bcp14>SHOULD</bcp14> store at least | |||
the three high-order bits of the mode attribute (MODE4_SUID, | the three high-order bits of the mode attribute (MODE4_SUID, | |||
MODE4_SGID, MODE4_SVTX). The server SHOULD return a mode | MODE4_SGID, MODE4_SVTX). The server <bcp14>SHOULD</bcp14> return a mod e | |||
attribute if one is requested, and the low-order nine bits of | attribute if one is requested, and the low-order nine bits of | |||
the mode (MODE4_R*, MODE4_W*, MODE4_X*) MUST match the result | the mode (MODE4_R*, MODE4_W*, MODE4_X*) <bcp14>MUST</bcp14> match the result | |||
of applying the method in | of applying the method in | |||
<xref target="computemode" /> to the ACL attribute. | <xref target="computemode" format="default"/> to the ACL attribute. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Creating New Objects" anchor="aclcreate"> | <section anchor="aclcreate" numbered="true" toc="default"> | |||
<t> | <name>Creating New Objects</name> | |||
<t> | ||||
If a server supports any ACL attributes, it may use the ACL | If a server supports any ACL attributes, it may use the ACL | |||
attributes on the parent directory to compute an initial ACL | attributes on the parent directory to compute an initial ACL | |||
attribute for a newly created object. This will be referred to | attribute for a newly created object. This will be referred to | |||
as the inherited ACL within this section. The act of adding | as the inherited ACL within this section. The act of adding | |||
one or more ACEs to the inherited ACL that are based upon ACEs | one or more ACEs to the inherited ACL that are based upon ACEs | |||
in the parent directory's ACL will be referred to as | in the parent directory's ACL will be referred to as | |||
inheriting an ACE within this section. | inheriting an ACE within this section. | |||
</t> | </t> | |||
<t> | <t> | |||
Implementors should standardize what the behavior of CREATE | Implementors should standardize what the behavior of CREATE | |||
and OPEN must be depending on the presence or absence of the | and OPEN must be depending on the presence or absence of the | |||
mode and ACL attributes. | mode and ACL attributes. | |||
<list style="numbers"> | </t> | |||
<t>If just the mode is given in the call: | <ol spacing="normal" type="1"> | |||
<vspace blankLines="1" /> In this case, inheritance | <li> | |||
SHOULD take place, but the mode MUST be applied to the | <t>If just the mode is given in the call: | |||
inherited ACL as described in <xref target="setmode" | </t> | |||
/>, thereby modifying the ACL. | <t> In this case, inheritance | |||
<bcp14>SHOULD</bcp14> take place, but the mode <bcp14>MUST</bcp14> | ||||
be applied to the | ||||
inherited ACL as described in <xref target="setmode" format="defau | ||||
lt"/>, thereby modifying the ACL. | ||||
</t> | </t> | |||
<t>If just the ACL is given in the call: | </li> | |||
<vspace blankLines="1" /> | <li> | |||
In this case, inheritance SHOULD NOT take place, and | <t>If just the ACL is given in the call: | |||
</t> | ||||
<t> | ||||
In this case, inheritance <bcp14>SHOULD NOT</bcp14> take place, an | ||||
d | ||||
the ACL as defined in the CREATE or OPEN will be set | the ACL as defined in the CREATE or OPEN will be set | |||
without modification, and the mode modified as in | without modification, and the mode modified as in | |||
<xref target="settingacl" />. | <xref target="settingacl" format="default"/>. | |||
</t> | </t> | |||
<t>If both mode and ACL are given in the call: | </li> | |||
<vspace blankLines="1" /> In this case, inheritance | <li> | |||
SHOULD NOT take place, and both attributes will be set | <t>If both mode and ACL are given in the call: | |||
as described in <xref target="setboth" />. | </t> | |||
<t> In this case, inheritance | ||||
<bcp14>SHOULD NOT</bcp14> take place, and both attributes will be | ||||
set | ||||
as described in <xref target="setboth" format="default"/>. | ||||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
If neither mode nor ACL is given in the call: | If neither mode nor ACL is given in the call: | |||
<vspace blankLines="1" /> | </t> | |||
<t> | ||||
In the case where an object is being created without | In the case where an object is being created without | |||
any initial attributes at all, e.g., an OPEN operation | any initial attributes at all, e.g., an OPEN operation | |||
with an opentype4 of OPEN4_CREATE and a createmode4 of | with an opentype4 of OPEN4_CREATE and a createmode4 of | |||
EXCLUSIVE4, inheritance SHOULD NOT take place (note that | EXCLUSIVE4, inheritance <bcp14>SHOULD NOT</bcp14> take place (note that | |||
EXCLUSIVE4_1 is a better choice of createmode4, since it | EXCLUSIVE4_1 is a better choice of createmode4, since it | |||
does permit initial attributes). | does permit initial attributes). | |||
Instead, the server SHOULD set permissions to deny all | Instead, the server <bcp14>SHOULD</bcp14> set permissions to deny all | |||
access to the newly created object. It is expected | access to the newly created object. It is expected | |||
that the appropriate client will set the desired | that the appropriate client will set the desired | |||
attributes in a subsequent SETATTR operation, and the | attributes in a subsequent SETATTR operation, and the | |||
server SHOULD allow that operation to succeed, | server <bcp14>SHOULD</bcp14> allow that operation to succeed, | |||
regardless of what permissions the object is created | regardless of what permissions the object is created | |||
with. For example, an empty ACL denies all | with. For example, an empty ACL denies all | |||
permissions, but the server should allow the owner's | permissions, but the server should allow the owner's | |||
SETATTR to succeed even though WRITE_ACL is implicitly | SETATTR to succeed even though WRITE_ACL is implicitly | |||
denied. | denied. | |||
<vspace blankLines="1" /> | </t> | |||
In other cases, inheritance SHOULD take place, and no | <t> | |||
In other cases, inheritance <bcp14>SHOULD</bcp14> take place, and | ||||
no | ||||
modifications to the ACL will happen. The mode | modifications to the ACL will happen. The mode | |||
attribute, if supported, MUST be as computed in | attribute, if supported, <bcp14>MUST</bcp14> be as computed in | |||
<xref target="computemode" />, with the MODE4_SUID, | <xref target="computemode" format="default"/>, with the MODE4_SUID, | |||
MODE4_SGID, and MODE4_SVTX bits clear. | MODE4_SGID, and MODE4_SVTX bits clear. | |||
If no inheritable ACEs exist on the parent directory, | If no inheritable ACEs exist on the parent directory, | |||
the rules for creating acl, dacl, or sacl attributes | the rules for creating acl, dacl, or sacl attributes | |||
are implementation defined. | are implementation defined. | |||
If either the dacl or sacl attribute is supported, | If either the dacl or sacl attribute is supported, | |||
then the ACL4_DEFAULTED flag SHOULD be set on the | then the ACL4_DEFAULTED flag <bcp14>SHOULD</bcp14> be set on the | |||
newly created attributes. | newly created attributes. | |||
<vspace blankLines='1' /> | </t> | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | <section anchor="inheritreq" numbered="true" toc="default"> | |||
<section title="The Inherited ACL" anchor="inheritreq"> | <name>The Inherited ACL</name> | |||
<t> | <t> | |||
If the object being created is not a directory, the | If the object being created is not a directory, the | |||
inherited ACL SHOULD NOT inherit ACEs from the parent | inherited ACL <bcp14>SHOULD NOT</bcp14> inherit ACEs from the parent | |||
directory ACL unless the ACE4_FILE_INHERIT_FLAG is set. | directory ACL unless the ACE4_FILE_INHERIT_FLAG is set. | |||
</t> | </t> | |||
<t> | <t> | |||
If the object being created is a directory, the inherited | If the object being created is a directory, the inherited | |||
ACL should inherit all inheritable ACEs from the parent | ACL should inherit all inheritable ACEs from the parent | |||
directory, that is, those that have the ACE4_FILE_INHERIT_ACE or | directory, that is, those that have the ACE4_FILE_INHERIT_ACE or | |||
ACE4_DIRECTORY_INHERIT_ACE flag set. | ACE4_DIRECTORY_INHERIT_ACE flag set. | |||
If the inheritable | If the inheritable | |||
ACE has ACE4_FILE_INHERIT_ACE set but | ACE has ACE4_FILE_INHERIT_ACE set but | |||
ACE4_DIRECTORY_INHERIT_ACE is clear, the inherited ACE on | ACE4_DIRECTORY_INHERIT_ACE is clear, the inherited ACE on | |||
the newly created directory MUST have the | the newly created directory <bcp14>MUST</bcp14> have the | |||
ACE4_INHERIT_ONLY_ACE flag set to prevent the directory | ACE4_INHERIT_ONLY_ACE flag set to prevent the directory | |||
from being affected by ACEs meant for non-directories. | from being affected by ACEs meant for non-directories. | |||
</t> | </t> | |||
<t> | <t> | |||
When a new directory is created, the server MAY split | When a new directory is created, the server <bcp14>MAY</bcp14> split | |||
any inherited ACE that is both inheritable and effective | any inherited ACE that is both inheritable and effective | |||
(in other words, that has neither ACE4_INHERIT_ONLY_ACE | (in other words, that has neither ACE4_INHERIT_ONLY_ACE | |||
nor ACE4_NO_PROPAGATE_INHERIT_ACE set), into two ACEs, | nor ACE4_NO_PROPAGATE_INHERIT_ACE set), into two ACEs, | |||
one with no inheritance flags and one with | one with no inheritance flags and one with | |||
ACE4_INHERIT_ONLY_ACE set. (In the case of a dacl or | ACE4_INHERIT_ONLY_ACE set. (In the case of a dacl or | |||
sacl attribute, both of those ACEs SHOULD also have the | sacl attribute, both of those ACEs <bcp14>SHOULD</bcp14> also have t he | |||
ACE4_INHERITED_ACE flag set.) This makes it simpler to | ACE4_INHERITED_ACE flag set.) This makes it simpler to | |||
modify the effective permissions on the directory | modify the effective permissions on the directory | |||
without modifying the ACE that is to be inherited to the | without modifying the ACE that is to be inherited to the | |||
new directory's children. | new directory's children. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="auto_inherit" numbered="true" toc="default"> | ||||
<section title="Automatic Inheritance" anchor="auto_inherit"> | <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">sacl</xref> | the <xref target="attrdef_sacl" format="default">sacl</xref> | |||
and <xref target="attrdef_dacl">dacl</xref> attributes | and <xref target="attrdef_dacl" format="default">dacl</xref> attribu | |||
tes | ||||
also include an additional flag field. | also include an additional flag field. | |||
<figure> | </t> | |||
<artwork> | <sourcecode type="xdr"><![CDATA[ | |||
struct nfsacl41 { | struct nfsacl41 { | |||
aclflag4 na41_flag; | aclflag4 na41_flag; | |||
nfsace4 na41_aces<>; | nfsace4 na41_aces<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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: | |||
<figure> | </t> | |||
<artwork> | <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; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <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> | |||
<t> | <t> | |||
Together these features allow a server to support automatic | Together these features allow a server to support automatic | |||
inheritance, which we now explain in more detail. | inheritance, which we now explain in more detail. | |||
</t> | </t> | |||
<t> | <t> | |||
Inheritable ACEs are normally inherited by child objects only | Inheritable ACEs are normally inherited by child objects only | |||
at the time that the child objects are created; later | at the time that the child objects are created; later | |||
modifications to inheritable ACEs do not result in | modifications to inheritable ACEs do not result in | |||
modifications to inherited ACEs on descendants. | modifications to inherited ACEs on descendants. | |||
</t> | </t> | |||
<t> | <t> | |||
However, the dacl and sacl provide an OPTIONAL mechanism | However, the dacl and sacl provide an <bcp14>OPTIONAL</bcp14> mechan | |||
ism | ||||
that allows a client application to propagate changes to | that allows a client application to propagate changes to | |||
inheritable ACEs to an entire directory hierarchy. | inheritable ACEs to an entire directory hierarchy. | |||
</t> | </t> | |||
<t> | <t> | |||
A server that supports this performs inheritance at object | A server that supports this performs inheritance at object | |||
creation time in the normal way, and SHOULD set the | creation time in the normal way, and <bcp14>SHOULD</bcp14> set the | |||
ACE4_INHERITED_ACE flag on any inherited ACEs as they are | ACE4_INHERITED_ACE flag on any inherited ACEs as they are | |||
added to the new object. | added to the new object. | |||
</t> | </t> | |||
<t> | <t> | |||
A client application such as an ACL editor may then propagate | A client application such as an ACL editor may then propagate | |||
changes to inheritable ACEs on a directory by recursively | changes to inheritable ACEs on a directory by recursively | |||
traversing that directory's descendants and modifying each ACL | traversing that directory's descendants and modifying each ACL | |||
encountered to remove any ACEs with the ACE4_INHERITED_ACE flag | encountered to remove any ACEs with the ACE4_INHERITED_ACE flag | |||
and to replace them by the new inheritable ACEs (also with the | and to replace them by the new inheritable ACEs (also with the | |||
ACE4_INHERITED_ACE flag set). It uses the existing ACE | ACE4_INHERITED_ACE flag set). It uses the existing ACE | |||
inheritance flags in the obvious way to decide which ACEs to | inheritance flags in the obvious way to decide which ACEs to | |||
propagate. (Note that it may encounter further inheritable | propagate. (Note that it may encounter further inheritable | |||
ACEs when descending the directory hierarchy and that those | ACEs when descending the directory hierarchy and that those | |||
will also need to be taken into account when propagating | will also need to be taken into account when propagating | |||
inheritable ACEs to further descendants.) | inheritable ACEs to further descendants.) | |||
</t> | </t> | |||
<t> | <t> | |||
The reach of this propagation may be limited in two ways: | The reach of this propagation may be limited in two ways: | |||
first, automatic inheritance is not performed from any | first, automatic inheritance is not performed from any | |||
directory ACL that has the ACL4_AUTO_INHERIT flag | directory ACL that has the ACL4_AUTO_INHERIT flag | |||
cleared; and second, automatic inheritance stops wherever | cleared; and second, automatic inheritance stops wherever | |||
an ACL with the ACL4_PROTECTED flag is set, preventing | an ACL with the ACL4_PROTECTED flag is set, preventing | |||
modification of that ACL and also (if the ACL is set on | modification of that ACL and also (if the ACL is set on | |||
a directory) of the ACL on any of the object's descendants. | a directory) of the ACL on any of the object's descendants. | |||
</t> | </t> | |||
<t> | <t> | |||
This propagation is performed independently for the sacl | This propagation is performed independently for the sacl | |||
and the dacl attributes; thus, the ACL4_AUTO_INHERIT and | and the dacl attributes; thus, the ACL4_AUTO_INHERIT and | |||
ACL4_PROTECTED flags may be independently set for the sacl | ACL4_PROTECTED flags may be independently set for the sacl | |||
and the dacl, and propagation of one type of acl may continue | and the dacl, and propagation of one type of acl may continue | |||
down a hierarchy even where propagation of the other acl has | down a hierarchy even where propagation of the other acl has | |||
stopped. | stopped. | |||
</t> | </t> | |||
<t> | <t> | |||
New objects should be created with a dacl and a sacl that | New objects should be created with a dacl and a sacl that | |||
both have the ACL4_PROTECTED flag cleared and the | both have the ACL4_PROTECTED flag cleared and the | |||
ACL4_AUTO_INHERIT flag set to the same value as that on, | ACL4_AUTO_INHERIT flag set to the same value as that on, | |||
respectively, the sacl or dacl of the parent object. | respectively, the sacl or dacl of the parent object. | |||
</t> | </t> | |||
<t> | <t> | |||
Both the dacl and sacl attributes are RECOMMENDED, and a server | Both the dacl and sacl attributes are <bcp14>RECOMMENDED</bcp14>, an | |||
d a server | ||||
may support one without supporting the other. | may support one without supporting the other. | |||
</t> | </t> | |||
<t> | <t> | |||
A server that supports both the old acl attribute and | A server that supports both the old acl attribute and | |||
one or both of the new dacl or sacl attributes must do so | one or both of the new dacl or sacl attributes must do so | |||
in such a way as to keep all three attributes consistent | in such a way as to keep all three attributes consistent | |||
with each other. Thus, the ACEs reported in the acl attribute | with each other. Thus, the ACEs reported in the acl attribute | |||
should be the union of the ACEs reported in the dacl and | should be the union of the ACEs reported in the dacl and | |||
sacl attributes, except that the ACE4_INHERITED_ACE flag must | sacl attributes, except that the ACE4_INHERITED_ACE flag must | |||
be cleared from the ACEs in the acl. And of course a | be cleared from the ACEs in the acl. And of course a | |||
client that queries only the acl will be unable to determine | client that queries only the acl will be unable to determine | |||
the values of the sacl or dacl flag fields. | the values of the sacl or dacl flag fields. | |||
</t> | </t> | |||
<t> | <t> | |||
When a client performs a SETATTR for the acl attribute, | When a client performs a SETATTR for the acl attribute, | |||
the server SHOULD set the ACL4_PROTECTED flag to true on | the server <bcp14>SHOULD</bcp14> set the ACL4_PROTECTED flag to true on | |||
both the sacl and the dacl. By using the acl attribute, | both the sacl and the dacl. By using the acl attribute, | |||
as opposed to the dacl or sacl attributes, the client signals | as opposed to the dacl or sacl attributes, the client signals | |||
that it may not understand automatic inheritance, and thus | that it may not understand automatic inheritance, and thus | |||
cannot be trusted to set an ACL for which automatic | cannot be trusted to set an ACL for which automatic | |||
inheritance would make sense. | inheritance would make sense. | |||
</t> | </t> | |||
<t> | <t> | |||
When a client application queries an ACL, modifies it, and sets | When a client application queries an ACL, modifies it, and sets | |||
it again, it should leave any ACEs marked with | it again, it should leave any ACEs marked with | |||
ACE4_INHERITED_ACE unchanged, in their original order, at the | ACE4_INHERITED_ACE unchanged, in their original order, at the | |||
end of the ACL. If the application is unable to do this, it | end of the ACL. If the application is unable to do this, it | |||
should set the ACL4_PROTECTED flag. This behavior | should set the ACL4_PROTECTED flag. This behavior | |||
is not enforced by servers, but violations of this rule may | is not enforced by servers, but violations of this rule may | |||
lead to unexpected results when applications perform automatic | lead to unexpected results when applications perform automatic | |||
inheritance. | inheritance. | |||
</t> | </t> | |||
<t> | <t> | |||
If a server also supports the mode attribute, it SHOULD set the | If a server also supports the mode attribute, it <bcp14>SHOULD</bcp1 | |||
4> set the | ||||
mode in such a way that leaves inherited ACEs unchanged, in | mode in such a way that leaves inherited ACEs unchanged, in | |||
their original order, at the end of the ACL. If it is unable | their original order, at the end of the ACL. If it is unable | |||
to do so, it SHOULD set the ACL4_PROTECTED flag on the file's | to do so, it <bcp14>SHOULD</bcp14> set the ACL4_PROTECTED flag on th e file's | |||
dacl. | dacl. | |||
</t> | </t> | |||
<t>Finally, in the case where the request that creates a new file | <t>Finally, in the case where the request that creates a new file | |||
or directory does not also set permissions for that file or | or directory does not also set permissions for that file or | |||
directory, and there are also no ACEs to inherit from the | directory, and there are also no ACEs to inherit from the | |||
parent's directory, then the server's choice of ACL for the new | parent's directory, then the server's choice of ACL for the new | |||
object is implementation-dependent. In this case, the server | object is implementation-dependent. In this case, the server | |||
SHOULD set the ACL4_DEFAULTED flag on the ACL it chooses for | <bcp14>SHOULD</bcp14> set the ACL4_DEFAULTED flag on the ACL it choo ses 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> | <section anchor="single_server_namespace" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Single-Server Namespace</name> | |||
$ --> | <t> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | ||||
<!-- Copyright (C) The Internet Society (2006) --> | ||||
<section anchor="single_server_namespace" title="Single-Server Namespace"> | ||||
<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' />. | to clients, as described in <xref target="NEW11" format="default"/>. | |||
</t> | </t> | |||
<section anchor="server_exports" title="Server Exports"> | <section anchor="server_exports" numbered="true" toc="default"> | |||
<t> | <name>Server Exports</name> | |||
<t> | ||||
On a UNIX server, the namespace describes all the files reachable by | On a UNIX server, the namespace describes all the files reachable by | |||
pathnames under the root directory or "/". On a Windows server, the | pathnames under the root directory or "/". On a Windows server, the | |||
namespace constitutes all the files on disks named by mapped disk | namespace constitutes all the files on disks named by mapped disk | |||
letters. NFS server administrators rarely make the entire server's | letters. NFS server administrators rarely make the entire server's | |||
file system namespace available to NFS clients. More often, portions | file system namespace available to NFS clients. More often, portions | |||
of the namespace are made available via an "export" feature. In | of the namespace are made available via an "export" feature. In | |||
previous versions of the NFS protocol, the root filehandle for each | previous versions of the NFS protocol, the root filehandle for each | |||
export is obtained through the MOUNT protocol; the client sent a | export is obtained through the MOUNT protocol; the client sent a | |||
string that identified the export name within the namespace and | string that identified the export name within the namespace and | |||
the server returned the root filehandle | the server returned the root filehandle | |||
for that export. The MOUNT protocol also provided an EXPORTS | for that export. The MOUNT protocol also provided an EXPORTS | |||
procedure that enumerated the server's exports. | procedure that enumerated the server's exports. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="browsing_exports" title="Browsing Exports"> | <section anchor="browsing_exports" numbered="true" toc="default"> | |||
<t> | <name>Browsing Exports</name> | |||
<t> | ||||
The NFSv4.1 protocol provides a root filehandle that clients can | The NFSv4.1 protocol provides a root filehandle that clients can | |||
use to obtain filehandles for the exports of a particular server, | use to obtain filehandles for the exports of a particular server, | |||
via a series of LOOKUP operations within a COMPOUND, to traverse | via a series of LOOKUP operations within a COMPOUND, to traverse | |||
a path. A common user experience is to use a graphical user interface | a path. A common user experience is to use a graphical user interface | |||
(perhaps a file "Open" dialog window) to find a file via progressive | (perhaps a file "Open" dialog window) to find a file via progressive | |||
browsing through a directory tree. The client must be able to move | browsing through a directory tree. The client must be able to move | |||
from one export to another export via single-component, progressive | from one export to another export via single-component, progressive | |||
LOOKUP operations. | LOOKUP operations. | |||
</t> | </t> | |||
<t> | <t> | |||
This style of browsing is not well supported by the NFSv3 protocol. In NF Sv3, the client expects all | This style of browsing is not well supported by the NFSv3 protocol. In NF Sv3, the client expects all | |||
LOOKUP operations to remain | LOOKUP operations to remain | |||
within a single server file system. For example, the device attribute | within a single server file system. For example, the device attribute | |||
will not change. This prevents a client from taking namespace paths | will not change. This prevents a client from taking namespace paths | |||
that span exports. | that span exports. | |||
</t> | </t> | |||
<t> | <t> | |||
In the case of NFSv3, an automounter on the client | In the case of NFSv3, an automounter on the client | |||
can obtain a snapshot of the server's namespace | can obtain a snapshot of the server's namespace | |||
using the EXPORTS procedure of the MOUNT protocol. | using the EXPORTS procedure of the MOUNT protocol. | |||
If it understands the server's pathname syntax, | If it understands the server's pathname syntax, | |||
it can create an image of the server's namespace | it can create an image of the server's namespace | |||
on the client. The parts of the namespace that | on the client. The parts of the namespace that | |||
are not exported by the server are filled in | are not exported by the server are filled in | |||
with directories that might be constructed similarly | with directories that might be constructed similarly | |||
to an NFSv4.1 "pseudo file system" (see <xref | to an NFSv4.1 "pseudo file system" (see <xref target="server_pseudo_file_s | |||
target="server_pseudo_file_system" />) that | ystem" format="default"/>) that | |||
allows the user to browse from one mounted file | allows the user to browse from one mounted file | |||
system to another. There is a drawback to this | system to another. There is a drawback to this | |||
representation of the server's namespace on the | representation of the server's namespace on the | |||
client: it is static. If the server administrator | client: it is static. If the server administrator | |||
adds a new export, the client will be unaware of it. | adds a new export, the client will be unaware of it. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="server_pseudo_file_system" title="Server Pseudo File System"> | <section anchor="server_pseudo_file_system" numbered="true" toc="default"> | |||
<t> | <name>Server Pseudo File System</name> | |||
<t> | ||||
NFSv4.1 servers avoid this namespace inconsistency by | NFSv4.1 servers avoid this namespace inconsistency by | |||
presenting all the exports for a given server within the | presenting all the exports for a given server within the | |||
framework of a single namespace for that server. | framework of a single namespace for that server. | |||
An NFSv4.1 client uses LOOKUP and READDIR | An NFSv4.1 client uses LOOKUP and READDIR | |||
operations to browse seamlessly from one export to another. | operations to browse seamlessly from one export to another. | |||
</t> | </t> | |||
<t> | <t> | |||
Where there are portions of the server namespace that are not | Where there are portions of the server namespace that are not | |||
exported, clients require some way of traversing those portions | exported, clients require some way of traversing those portions | |||
to reach actual exported file systems. A technique that servers | to reach actual exported file systems. A technique that servers | |||
may use to provide for this is to bridge the unexported portion of | may use to provide for this is to bridge the unexported portion of | |||
the namespace via a | the namespace via a | |||
"pseudo file system" that provides a view of exported directories | "pseudo file system" that provides a view of exported directories | |||
only. A pseudo file system has a unique fsid and behaves like a | only. A pseudo file system has a unique fsid and behaves like a | |||
normal, read-only file system. | normal, read-only file system. | |||
</t> | </t> | |||
<t> | <t> | |||
Based on the construction of the server's namespace, it is possible | Based on the construction of the server's namespace, it is possible | |||
that multiple pseudo file systems may exist. For example, | that multiple pseudo file systems may exist. For example, | |||
</t> | </t> | |||
<figure> | <artwork name="" type="" align="left" alt=""><![CDATA[ | |||
<artwork> | ||||
/a pseudo file system | /a pseudo file system | |||
/a/b real file system | /a/b real file system | |||
/a/b/c pseudo file system | /a/b/c pseudo file system | |||
/a/b/c/d real file system | /a/b/c/d real file system | |||
</artwork> | ]]></artwork> | |||
</figure> | <t> | |||
<t> | ||||
Each of the pseudo file systems is considered a separate entity and | Each of the pseudo file systems is considered a separate entity and | |||
therefore MUST have its own fsid, unique among all the fsids for that | therefore <bcp14>MUST</bcp14> have its own fsid, unique among all the fsid s for that | |||
server. | server. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Multiple Roots"> | <section numbered="true" toc="default"> | |||
<t> | <name>Multiple Roots</name> | |||
<t> | ||||
Certain operating environments are sometimes described as | Certain operating environments are sometimes described as | |||
having "multiple roots". In such environments, individual file | having "multiple roots". In such environments, individual file | |||
systems are commonly represented by disk or volume names. | systems are commonly represented by disk or volume names. | |||
NFSv4 servers for these platforms can construct a pseudo file | NFSv4 servers for these platforms can construct a pseudo file | |||
system above these root names so that disk letters or volume names are | system above these root names so that disk letters or volume names are | |||
simply directory names in the pseudo root. | simply directory names in the pseudo root. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Filehandle Volatility" anchor="pseudo_fs_volatility" > | <section anchor="pseudo_fs_volatility" numbered="true" toc="default"> | |||
<t> | <name>Filehandle Volatility</name> | |||
<t> | ||||
The nature of the server's pseudo file system is that it is a logical | The nature of the server's pseudo file system is that it is a logical | |||
representation of file system(s) available from the server. | representation of file system(s) available from the server. | |||
Therefore, the pseudo file system is most likely constructed | Therefore, the pseudo file system is most likely constructed | |||
dynamically when the server is first instantiated. It is expected | dynamically when the server is first instantiated. It is expected | |||
that the pseudo file system may not have an on-disk counterpart from | that the pseudo file system may not have an on-disk counterpart from | |||
which persistent filehandles could be constructed. Even though it is | which persistent filehandles could be constructed. Even though it is | |||
preferable that the server provide persistent filehandles for the | preferable that the server provide persistent filehandles for the | |||
pseudo file system, the NFS client should expect that pseudo file | pseudo file system, the NFS client should expect that pseudo file | |||
system filehandles are volatile. This can be confirmed by checking | system filehandles are volatile. This can be confirmed by checking | |||
the associated "fh_expire_type" attribute for those filehandles in | the associated "fh_expire_type" attribute for those filehandles in | |||
question. If the filehandles are volatile, the NFS client must be | question. If the filehandles are volatile, the NFS client must be | |||
prepared to recover a filehandle value (e.g., with a series of | prepared to recover a filehandle value (e.g., with a series of | |||
LOOKUP operations) when receiving an error of NFS4ERR_FHEXPIRED. | LOOKUP operations) when receiving an error of NFS4ERR_FHEXPIRED. | |||
</t> | </t> | |||
<t> | <t> | |||
Because it is quite likely that servers will implement pseudo | Because it is quite likely that servers will implement pseudo | |||
file systems using volatile filehandles, clients need to be | file systems using volatile filehandles, clients need to be | |||
prepared for them, rather than assuming that all filehandles | prepared for them, rather than assuming that all filehandles | |||
will be persistent. | will be persistent. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Exported Root"> | <section numbered="true" toc="default"> | |||
<t> | <name>Exported Root</name> | |||
<t> | ||||
If the server's root file system is exported, one might conclude that | If the server's root file system is exported, one might conclude that | |||
a pseudo file system is unneeded. This is not necessarily so. Assume the | a pseudo file system is unneeded. This is not necessarily so. Assume the | |||
following file systems on a server: | following file systems on a server: | |||
</t> | </t> | |||
<figure> | <artwork name="" type="" align="left" alt=""><![CDATA[ | |||
<artwork> | ||||
/ fs1 (exported) | / fs1 (exported) | |||
/a fs2 (not exported) | /a fs2 (not exported) | |||
/a/b fs3 (exported) | /a/b fs3 (exported)]]></artwork> | |||
</artwork> | <t> | |||
</figure> | ||||
<t> | ||||
Because fs2 is not exported, fs3 cannot be reached with simple | Because fs2 is not exported, fs3 cannot be reached with simple | |||
LOOKUPs. The server must bridge the gap with a pseudo file system. | LOOKUPs. The server must bridge the gap with a pseudo file system. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Mount Point Crossing"> | <section numbered="true" toc="default"> | |||
<t> | <name>Mount Point Crossing</name> | |||
<t> | ||||
The server file system environment may be constructed in such a way | The server file system environment may be constructed in such a way | |||
that one file system contains a directory that is 'covered' or | that one file system contains a directory that is 'covered' or | |||
mounted upon by a second file system. For example: | mounted upon by a second file system. For example: | |||
</t> | </t> | |||
<figure> | <artwork name="" type="" align="left" alt=""><![CDATA[ | |||
<artwork> | ||||
/a/b (file system 1) | /a/b (file system 1) | |||
/a/b/c/d (file system 2) | /a/b/c/d (file system 2)]]></artwork> | |||
</artwork> | <t> | |||
</figure> | ||||
<t> | ||||
The pseudo file system for this server may be constructed to look | The pseudo file system for this server may be constructed to look | |||
like: | like: | |||
</t> | </t> | |||
<figure> | <artwork name="" type="" align="left" alt=""><![CDATA[ | |||
<artwork> | ||||
/ (place holder/not exported) | / (place holder/not exported) | |||
/a/b (file system 1) | /a/b (file system 1) | |||
/a/b/c/d (file system 2) | /a/b/c/d (file system 2)]]></artwork> | |||
</artwork> | <t> | |||
</figure> | ||||
<t> | ||||
It is the server's responsibility to present the pseudo file system | It is the server's responsibility to present the pseudo file system | |||
that is complete to the client. If the client sends a LOOKUP request | that is complete to the client. If the client sends a LOOKUP request | |||
for the path /a/b/c/d, the server's response is the filehandle of | for the path /a/b/c/d, the server's response is the filehandle of | |||
the root of the file system /a/b/c/d. In previous versions of the | the root of the file system /a/b/c/d. In previous versions of the | |||
NFS protocol, | NFS protocol, | |||
the server would respond with the filehandle of directory | the server would respond with the filehandle of directory | |||
/a/b/c/d within the file system /a/b. | /a/b/c/d within the file system /a/b. | |||
</t> | </t> | |||
<t> | <t> | |||
The NFS client will be able to determine if it crosses a server mount | The NFS client will be able to determine if it crosses a server mount | |||
point by a change in the value of the "fsid" attribute. | point by a change in the value of the "fsid" attribute. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Security Policy and Namespace Presentation"> | <section numbered="true" toc="default"> | |||
<t> | <name>Security Policy and Namespace Presentation</name> | |||
<t> | ||||
Because NFSv4 clients possess the ability to change the security | Because NFSv4 clients possess the ability to change the security | |||
mechanisms used, after determining what is allowed, | mechanisms used, after determining what is allowed, | |||
by using SECINFO and SECINFO_NONAME, the server | by using SECINFO and SECINFO_NONAME, the server | |||
SHOULD NOT present a different view of the namespace based on | <bcp14>SHOULD NOT</bcp14> present a different view of the namespace based on | |||
the security mechanism being used by a client. Instead, it | the security mechanism being used by a client. Instead, it | |||
should present a consistent view and return NFS4ERR_WRONGSEC | should present a consistent view and return NFS4ERR_WRONGSEC | |||
if an attempt is made to access data with an inappropriate | if an attempt is made to access data with an inappropriate | |||
security mechanism. | security mechanism. | |||
</t> | </t> | |||
<t> | <t> | |||
If security considerations make it necessary to hide the existence | If security considerations make it necessary to hide the existence | |||
of a particular file system, as opposed to all of the data within | of a particular file system, as opposed to all of the data within | |||
it, the server can apply the security policy of | it, the server can apply the security policy of | |||
a shared resource in the server's namespace to components of the | a shared resource in the server's namespace to components of the | |||
resource's ancestors. For example: | resource's ancestors. For example: | |||
</t> | </t> | |||
<figure> | <artwork name="" type="" align="left" alt=""><![CDATA[ | |||
<artwork> | ||||
/ (place holder/not exported) | / (place holder/not exported) | |||
/a/b (file system 1) | /a/b (file system 1) | |||
/a/b/MySecretProject (file system 2) | /a/b/MySecretProject (file system 2)]]></artwork> | |||
<t> | ||||
</artwork> | ||||
</figure> | ||||
<t> | ||||
The /a/b/MySecretProject directory is a real file system and | The /a/b/MySecretProject directory is a real file system and | |||
is the shared resource. | is the shared resource. | |||
Suppose the security policy for /a/b/MySecretProject is Kerberos | Suppose the security policy for /a/b/MySecretProject is Kerberos | |||
with integrity and it is desired to limit knowledge of the existence | with integrity and it is desired to limit knowledge of the existence | |||
of this file system. In this case, the | of this file system. In this case, the | |||
server should apply the same security policy to /a/b. This allows | server should apply the same security policy to /a/b. This allows | |||
for knowledge of the existence of a file system to be secured | for knowledge of the existence of a file system to be secured | |||
when desirable. | when desirable. | |||
</t> | </t> | |||
<t> | <t> | |||
For the case of the use of multiple, disjoint security mechanisms in | For the case of the use of multiple, disjoint security mechanisms in | |||
the server's resources, applying that sort of policy would result | the server's resources, applying that sort of policy would result | |||
in the higher-level file system not being accessible using any | in the higher-level file system not being accessible using any | |||
security flavor. | security flavor. | |||
Therefore, that sort of configuration is not compatible | Therefore, that sort of configuration is not compatible | |||
with hiding the existence (as opposed to the contents) from clients | with hiding the existence (as opposed to the contents) from clients | |||
using multiple disjoint sets of security flavors. | using multiple disjoint sets of security flavors. | |||
</t> | </t> | |||
<t> | <t> | |||
In other circumstances, a desirable policy is for the security of a | In other circumstances, a desirable policy is for the security of a | |||
particular object in the | particular object in the | |||
server's namespace to include the union of all security mechanisms of | server's namespace to include the union of all security mechanisms of | |||
all direct descendants. A common and convenient practice, unless | all direct descendants. A common and convenient practice, unless | |||
strong security requirements dictate otherwise, is to make the | strong security requirements dictate otherwise, is to make the | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section numbered="true" toc="default"> | |||
$ --> | <name>State Management</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <t> | |||
<!-- Copyright (C) The Internet Society (2006) --> | ||||
<section title="State Management" > | ||||
<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" />. These features include expanded | <xref target="xnfs" format="default"/>. These features include expanded | |||
locking facilities, which provide some measure of inter-client | locking facilities, which provide some measure of inter-client | |||
exclusion, but the state also offers | exclusion, but the state also offers | |||
features not readily providable using a stateless model. | features not readily providable using a stateless model. | |||
There are three components to | There are three components to | |||
making this state manageable: | making this state manageable: | |||
<list style='symbols'> | ||||
<t> | ||||
clear division between client and server | ||||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
clear division between client and server | ||||
</li> | ||||
<li> | ||||
ability to reliably detect inconsistency in state between client | ability to reliably detect inconsistency in state between client | |||
and server | and server | |||
</t> | </li> | |||
<t> | <li> | |||
simple and robust recovery mechanisms | simple and robust recovery mechanisms | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
In this model, the server owns the state information. The client | In this model, the server owns the state information. The client | |||
requests changes in locks and the server responds with the changes | requests changes in locks and the server responds with the changes | |||
made. Non-client-initiated changes in locking state are infrequent. | made. Non-client-initiated changes in locking state are infrequent. | |||
The client receives prompt notification of such changes and can adjust | The client receives prompt notification of such changes and can adjust | |||
its view of the locking state to reflect the server's changes. | its view of the locking state to reflect the server's changes. | |||
</t> | </t> | |||
<t> | <t> | |||
Individual pieces of state created by the server and passed to the | Individual pieces of state created by the server and passed to the | |||
client at its request are represented by 128-bit stateids. These | client at its request are represented by 128-bit stateids. These | |||
stateids may represent a particular open file, a set of | stateids may represent a particular open file, a set of | |||
byte-range locks held | byte-range locks held | |||
by a particular owner, or a recallable delegation of privileges | by a particular owner, or a recallable delegation of privileges | |||
to access a file in particular ways or at a particular location. | to access a file in particular ways or at a particular location. | |||
</t> | </t> | |||
<t> | <t> | |||
In all cases, there is a transition from the most general | In all cases, there is a transition from the most general | |||
information that represents a client as a whole to the eventual | information that represents a client as a whole to the eventual | |||
lightweight stateid used for most client and server | lightweight stateid used for most client and server | |||
locking interactions. The details of this transition will vary | locking interactions. The details of this transition will vary | |||
with the type of object but it always starts with a client ID. | with the type of object but it always starts with a client ID. | |||
</t> | </t> | |||
<section anchor="client_id" title="Client and Session ID" > | <section anchor="client_id" numbered="true" toc="default"> | |||
<t> | <name>Client and Session ID</name> | |||
A client must establish a client ID (see <xref target="Client_Identifiers" | <t> | |||
/>) | A client must establish a client ID (see <xref target="Client_Identifiers" | |||
and then one or more sessionids (see <xref target="Session" />) before | format="default"/>) | |||
and then one or more sessionids (see <xref target="Session" format="defaul | ||||
t"/>) before | ||||
performing any operations to open, byte-range lock, delegate, or obtain | performing any operations to open, byte-range lock, delegate, or obtain | |||
a layout for a file object. | a layout for a file object. | |||
Each session ID is associated with a specific client ID, and thus | Each session ID is associated with a specific client ID, and thus | |||
serves as a shorthand reference to an NFSv4.1 client. | serves as a shorthand reference to an NFSv4.1 client. | |||
</t> | </t> | |||
<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> <!-- "Client and Session ID" --> | </section> | |||
<section anchor="stateid" title="Stateid Definition" > | <section anchor="stateid" numbered="true" toc="default"> | |||
<t> | <name>Stateid Definition</name> | |||
<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 | |||
has its own | has its own | |||
identifying stateid. Delegations and layouts also have | identifying stateid. Delegations and layouts also have | |||
associated stateids by which they may be referenced. | associated stateids by which they may be referenced. | |||
The stateid is used as a shorthand reference to a lock or set | The stateid is used as a shorthand reference to a lock or set | |||
of locks, and given a stateid, the server can determine the associated | of locks, and given a stateid, the server can determine the associated | |||
state-owner or state-owners (in the case of an open-owner/lock-owner pai r) | state-owner or state-owners (in the case of an open-owner/lock-owner pai r) | |||
and the associated filehandle. When stateids are used, the current | and the associated filehandle. When stateids are used, the current | |||
filehandle must be the one associated with that stateid. | filehandle must be the one associated with that stateid. | |||
</t> | </t> | |||
<t> | <t> | |||
All stateids associated with a given client ID are associated with | All stateids associated with a given client ID are associated with | |||
a common lease that represents the claim of those stateids | a common lease that represents the claim of those stateids | |||
and the objects they represent to be maintained | and the objects they represent to be maintained | |||
by the server. See <xref target="lease_renewal" /> for a | by the server. See <xref target="lease_renewal" format="default"/> for a | |||
discussion of the lease. | discussion of the lease. | |||
</t> | </t> | |||
<t> | <t> | |||
The server may assign stateids independently for different clients. | The server may assign stateids independently for different clients. | |||
A stateid with the same bit pattern for one client may designate | A stateid with the same bit pattern for one client may designate | |||
an entirely different set of locks for a different client. The | an entirely different set of locks for a different client. The | |||
stateid is always interpreted with respect to the client ID associated | stateid is always interpreted with respect to the client ID associated | |||
with the current session. Stateids apply to all sessions associated | with the current session. Stateids apply to all sessions associated | |||
with the given client ID, and the client may use a stateid obtained from | with the given client ID, and the client may use a stateid obtained from | |||
one session on another session associated with the same client ID. | one session on another session associated with the same client ID. | |||
</t> | </t> | |||
<section anchor="stateid_types" title="Stateid Types"> | <section anchor="stateid_types" numbered="true" toc="default"> | |||
<t> | <name>Stateid Types</name> | |||
With the exception of special stateids (see <xref target="special_stat | <t> | |||
eid"/>), | With the exception of special stateids (see <xref target="special_stat | |||
eid" format="default"/>), | ||||
each stateid | each stateid | |||
represents locking objects of one of a set of types defined | represents locking objects of one of a set of types defined | |||
by the NFSv4.1 protocol. Note that in all these cases, where | by the NFSv4.1 protocol. Note that in all these cases, where | |||
we speak of guarantee, it is understood there are | we speak of guarantee, it is understood there are | |||
situations such as a client restart, or lock revocation, | situations such as a client restart, or lock revocation, | |||
that allow the guarantee to be voided. | that allow the guarantee to be voided. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
Stateids may represent opens of files. | Stateids may represent opens of files. | |||
<vspace blankLines="1" /> | </t> | |||
<t> | ||||
Each stateid in this case represents the OPEN state for a | Each stateid in this case represents the OPEN state for a | |||
given client ID/open-owner/filehandle triple. Such | given client ID/open-owner/filehandle triple. Such | |||
stateids are subject to change (with consequent | stateids are subject to change (with consequent | |||
incrementing of the stateid's seqid) in response to OPENs that | incrementing of the stateid's seqid) in response to OPENs that | |||
result in upgrade and OPEN_DOWNGRADE operations. | result in upgrade and OPEN_DOWNGRADE operations. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
Stateids may represent sets of byte-range locks. | Stateids may represent sets of byte-range locks. | |||
<vspace blankLines="1" /> | </t> | |||
<t> | ||||
All locks held on a particular file by a particular owner and | All locks held on a particular file by a particular owner and | |||
gotten under the aegis of a particular open file | gotten under the aegis of a particular open file | |||
are associated with a single stateid with the seqid | are associated with a single stateid with the seqid | |||
being incremented whenever LOCK and LOCKU operations affect that | being incremented whenever LOCK and LOCKU operations affect that | |||
set of locks. | set of locks. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
Stateids may represent file delegations, which are | Stateids may represent file delegations, which are | |||
recallable guarantees by the server to the client | recallable guarantees by the server to the client | |||
that other clients will not reference or | that other clients will not reference or | |||
modify a particular file, until the delegation | modify a particular file, until the delegation | |||
is returned. In NFSv4.1, file delegations may be | is returned. In NFSv4.1, file delegations may be | |||
obtained on both regular and non-regular files. | obtained on both regular and non-regular files. | |||
<vspace blankLines="1" /> | </t> | |||
<t> | ||||
A stateid represents a single delegation held by | A stateid represents a single delegation held by | |||
a client for a particular filehandle. | a client for a particular filehandle. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
Stateids may represent directory delegations, which | Stateids may represent directory delegations, which | |||
are recallable guarantees by the server to the client | are recallable guarantees by the server to the client | |||
that other clients will not modify the directory, | that other clients will not modify the directory, | |||
until the delegation is returned. | until the delegation is returned. | |||
<vspace blankLines="1" /> | </t> | |||
<t> | ||||
A stateid represents a single delegation held by | A stateid represents a single delegation held by | |||
a client for a particular directory filehandle. | a client for a particular directory filehandle. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
Stateids may represent layouts, which are recallable | Stateids may represent layouts, which are recallable | |||
guarantees by the server to the client that particular | guarantees by the server to the client that particular | |||
files may be accessed via an alternate data access | files may be accessed via an alternate data access | |||
protocol at specific locations. Such access is | protocol at specific locations. Such access is | |||
limited to particular sets of byte-ranges and may | limited to particular sets of byte-ranges and may | |||
proceed until those byte-ranges are reduced or the | proceed until those byte-ranges are reduced or the | |||
layout is returned. | layout is returned. | |||
<vspace blankLines="1" /> | </t> | |||
<t> | ||||
A stateid represents the set of all layouts held by a particular | A stateid represents the set of all layouts held by a particular | |||
client for a particular filehandle with a given | client for a particular filehandle with a given | |||
layout type. The seqid is updated as the layouts | layout type. The seqid is updated as the layouts | |||
of that set of byte-ranges change, via layout stateid changing ope rations such | of that set of byte-ranges change, via layout stateid changing ope rations such | |||
as LAYOUTGET and LAYOUTRETURN. | as LAYOUTGET and LAYOUTRETURN. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ul> | |||
</section> | </section> | |||
<section anchor="stateid_structure" title="Stateid Structure"> | <section anchor="stateid_structure" numbered="true" toc="default"> | |||
<t> | <name>Stateid Structure</name> | |||
<t> | ||||
Stateids are divided into two fields, a 96-bit | Stateids are divided into two fields, a 96-bit | |||
"other" field identifying the specific set | "other" field identifying the specific set | |||
of locks and a 32-bit "seqid" sequence value. | of locks and a 32-bit "seqid" sequence value. | |||
Except in the case of special stateids | Except in the case of special stateids | |||
(see <xref target="special_stateid"/>), | (see <xref target="special_stateid" format="default"/>), | |||
a particular value of the | a particular value of the | |||
"other" field denotes a | "other" field denotes a | |||
set of locks of the same type (for example, | set of locks of the same type (for example, | |||
byte-range locks, opens, delegations, or layouts), | byte-range locks, opens, delegations, or layouts), | |||
for a specific file or directory, and sharing | for a specific file or directory, and sharing | |||
the same ownership characteristics. The seqid | the same ownership characteristics. The seqid | |||
designates a specific instance of such a set of | designates a specific instance of such a set of | |||
locks, and is incremented to indicate changes in | locks, and is incremented to indicate changes in | |||
such a set of locks, either by the addition or | such a set of locks, either by the addition or | |||
deletion of locks from the set, a change in the | deletion of locks from the set, a change in the | |||
byte-range they apply to, or an upgrade or downgrade | byte-range they apply to, or an upgrade or downgrade | |||
in the type of one or more locks. | in the type of one or more locks. | |||
</t> | </t> | |||
<t> | <t> | |||
When such a set of locks is first created, the server returns a | When such a set of locks is first created, the server returns a | |||
stateid with seqid value of one. On subsequent | stateid with seqid value of one. On subsequent | |||
operations that modify the set of locks, the server | operations that modify the set of locks, the server | |||
is required to increment the "seqid" field by one | is required to increment the "seqid" field by one | |||
whenever it returns a stateid for the same | whenever it returns a stateid for the same | |||
state-owner/file/type combination and there is some | state-owner/file/type combination and there is some | |||
change in the set of locks actually designated. | change in the set of locks actually designated. | |||
In this case, the server will return a stateid with an "other" field | In this case, the server will return a stateid with an "other" field | |||
the same as previously used for that | the same as previously used for that | |||
state-owner/file/type combination, with an | state-owner/file/type combination, with an | |||
incremented "seqid" field. | incremented "seqid" field. | |||
This pattern continues until the seqid is incremented | This pattern continues until the seqid is incremented | |||
past NFS4_UINT32_MAX, and one | past NFS4_UINT32_MAX, and one | |||
(not zero) is the next seqid value. | (not zero) is the next seqid value. | |||
</t> | </t> | |||
<t> | <t> | |||
The purpose of the incrementing of the seqid | The purpose of the incrementing of the seqid | |||
is to allow the server to | is to allow the server to | |||
communicate to the client the order in which | communicate to the client the order in which | |||
operations that modified locking state associated | operations that modified locking state associated | |||
with a stateid have been processed and to make | with a stateid have been processed and to make | |||
it possible for the client to send requests | it possible for the client to send requests | |||
that are conditional on the set of locks not | that are conditional on the set of locks not | |||
having changed since the stateid in question | having changed since the stateid in question | |||
was returned. | was returned. | |||
</t> | </t> | |||
<t> | <t> | |||
Except for layout stateids (<xref target="layout_stateid"/>), | Except for layout stateids (<xref target="layout_stateid" format="defau | |||
lt"/>), | ||||
when a client sends a stateid to the server, it has two | when a client sends a stateid to the server, it has two | |||
choices with regard to the seqid sent. It may set the seqid | choices with regard to the seqid sent. It may set the seqid | |||
to zero to indicate to the server that it wishes the most | to zero to indicate to the server that it wishes the most | |||
up-to-date seqid for that stateid's "other" field to be | up-to-date seqid for that stateid's "other" field to be | |||
used. This would be the common choice in the case of a | used. This would be the common choice in the case of a | |||
stateid sent with a READ or WRITE operation. It also may | stateid sent with a READ or WRITE operation. It also may | |||
set a non-zero value, in which case the server checks if that | set a non-zero value, in which case the server checks if that | |||
seqid is the correct one. In that case, the server is | seqid is the correct one. In that case, the server is | |||
required to return NFS4ERR_OLD_STATEID if the seqid is lower | required to return NFS4ERR_OLD_STATEID if the seqid is lower | |||
than the most current value and NFS4ERR_BAD_STATEID if the | than the most current value and NFS4ERR_BAD_STATEID if the | |||
seqid is greater than the most current value. This would be | seqid is greater than the most current value. This would be | |||
the common choice in the case of stateids sent with a CLOSE | the common choice in the case of stateids sent with a CLOSE | |||
or OPEN_DOWNGRADE. Because OPENs may be sent in parallel | or OPEN_DOWNGRADE. Because OPENs may be sent in parallel | |||
for the same owner, a client might close a file without | for the same owner, a client might close a file without | |||
knowing that an OPEN upgrade had been done by the server, | knowing that an OPEN upgrade had been done by the server, | |||
changing the lock in question. If CLOSE were sent with a | changing the lock in question. If CLOSE were sent with a | |||
zero seqid, the OPEN upgrade would be cancelled before the | zero seqid, the OPEN upgrade would be cancelled before the | |||
client even received an indication that an upgrade had | client even received an indication that an upgrade had | |||
happened. | happened. | |||
</t> | </t> | |||
<t> | <t> | |||
When a stateid is sent by the server to the client as part of | When a stateid is sent by the server to the client as part of | |||
a callback operation, it is not subject to checking for | a callback operation, it is not subject to checking for | |||
a current seqid and returning NFS4ERR_OLD_STATEID. This | a current seqid and returning NFS4ERR_OLD_STATEID. This | |||
is because the client is not in a position to know the | is because the client is not in a position to know the | |||
most up-to-date seqid and thus cannot verify it. Unless | most up-to-date seqid and thus cannot verify it. Unless | |||
specially noted, the seqid value for a stateid sent by the | specially noted, the seqid value for a stateid sent by the | |||
server to the client as part of a callback is required | server to the client as part of a callback is required | |||
to be zero with NFS4ERR_BAD_STATEID returned if it is | to be zero with NFS4ERR_BAD_STATEID returned if it is | |||
not. | not. | |||
</t> | </t> | |||
<t> | <t> | |||
In making comparisons between seqids, both by the client | In making comparisons between seqids, both by the client | |||
in determining the order of operations and by the server | in determining the order of operations and by the server | |||
in determining whether the NFS4ERR_OLD_STATEID is to be | in determining whether the NFS4ERR_OLD_STATEID is to be | |||
returned, the possibility of the seqid being swapped | returned, the possibility of the seqid being swapped | |||
around past the NFS4_UINT32_MAX value needs to be taken | around past the NFS4_UINT32_MAX value needs to be taken | |||
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> <!-- "Stateid Structure" --> | <section anchor="special_stateid" numbered="true" toc="default"> | |||
<section anchor="special_stateid" title="Special Stateids"> | <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> | |||
The following combinations of "other" and "seqid" are defined | The following combinations of "other" and "seqid" are defined | |||
in NFSv4.1: | in NFSv4.1: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
When "other" and "seqid" are both zero, the | When "other" and "seqid" are both zero, the | |||
stateid is treated as a special anonymous | stateid is treated as a special anonymous | |||
stateid, which can be used in READ, WRITE, | stateid, which can be used in READ, WRITE, | |||
and SETATTR requests to indicate the absence | and SETATTR requests to indicate the absence | |||
of any OPEN state associated with the | of any OPEN state associated with the | |||
request. When an anonymous stateid value is | request. When an anonymous stateid value is | |||
used and an existing open denies the form of | used and an existing open denies the form of | |||
access requested, then access will be denied | access requested, then access will be denied | |||
to the request. This stateid MUST NOT be | to the request. This stateid <bcp14>MUST NOT</bcp14> be | |||
used on operations to data servers (<xref | used on operations to data servers (<xref target="ds_ops" format=" | |||
target="ds_ops" />). | default"/>). | |||
</t> | </li> | |||
<t> | <li> | |||
When "other" and "seqid" are both all ones, | When "other" and "seqid" are both all ones, | |||
the stateid is a special READ bypass stateid. | the stateid is a special READ bypass stateid. | |||
When this value is used in WRITE or SETATTR, | When this value is used in WRITE or SETATTR, | |||
it is treated like the anonymous value. | it is treated like the anonymous value. | |||
When used in READ, the server MAY grant | When used in READ, the server <bcp14>MAY</bcp14> grant | |||
access, even if access would normally be | access, even if access would normally be | |||
denied to READ operations. This stateid MUST | denied to READ operations. This stateid <bcp14>MUST | |||
NOT be used on operations to data servers. | NOT</bcp14> be used on operations to data servers. | |||
</t> | </li> | |||
<t> | <li> | |||
When "other" is zero and "seqid" is one, | When "other" is zero and "seqid" is one, | |||
the stateid represents the current stateid, | the stateid represents the current stateid, | |||
which is whatever value is the last stateid | which is whatever value is the last stateid | |||
returned by an operation within the COMPOUND. | returned by an operation within the COMPOUND. | |||
In the case of an OPEN, the stateid returned | In the case of an OPEN, the stateid returned | |||
for the open file and not the delegation is | for the open file and not the delegation is | |||
used. The stateid passed to the operation in | used. The stateid passed to the operation in | |||
place of the special value has its "seqid" | place of the special value has its "seqid" | |||
value set to zero, except when the current | value set to zero, except when the current | |||
stateid is used by the operation CLOSE or | stateid is used by the operation CLOSE or | |||
OPEN_DOWNGRADE. If there is no operation | OPEN_DOWNGRADE. If there is no operation | |||
in the COMPOUND that has returned a stateid | in the COMPOUND that has returned a stateid | |||
value, the server MUST return the error | value, the server <bcp14>MUST</bcp14> return the error | |||
NFS4ERR_BAD_STATEID. As illustrated in <xref | NFS4ERR_BAD_STATEID. As illustrated in <xref target="csid_example4 | |||
target="csid_example4"/>, if the value of a | " format="default"/>, if the value of a | |||
current stateid is a special stateid and the | current stateid is a special stateid and the | |||
stateid of an operation's arguments has | stateid of an operation's arguments has | |||
"other" set to zero and "seqid" set to one, | "other" set to zero and "seqid" set to one, | |||
then the server MUST return the error | then the server <bcp14>MUST</bcp14> return the error | |||
NFS4ERR_BAD_STATEID. | NFS4ERR_BAD_STATEID. | |||
</t> | </li> | |||
<t> | <li> | |||
When "other" is zero and "seqid" is NFS4_UINT32_MAX, | When "other" is zero and "seqid" is NFS4_UINT32_MAX, | |||
the stateid represents a reserved stateid | the stateid represents a reserved stateid | |||
value defined to be invalid. When this | value defined to be invalid. When this | |||
stateid is used, the server MUST return the error | stateid is used, the server <bcp14>MUST</bcp14> return the error | |||
NFS4ERR_BAD_STATEID. | NFS4ERR_BAD_STATEID. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
If a stateid value is used that has all zeros or all ones in the | If a stateid value is used that has all zeros or all ones in the | |||
"other" field but does not match one of the cases above, the server | "other" field but does not match one of the cases above, the server | |||
MUST return the error NFS4ERR_BAD_STATEID. | <bcp14>MUST</bcp14> return the error NFS4ERR_BAD_STATEID. | |||
</t> | </t> | |||
<t> | <t> | |||
Special stateids, unlike other stateids, are not associated with | Special stateids, unlike other stateids, are not associated with | |||
individual client IDs or filehandles and can be used with all valid | individual client IDs or filehandles and can be used with all valid | |||
client IDs and filehandles. In the case of a special | 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 c urrent | where the current filehandle does not match that associated with the c urrent | |||
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> <!-- "Special Stateids" --> | </section> | |||
<section anchor="stateid_lifetime" title="Stateid Lifetime and Validation" | <section anchor="stateid_lifetime" numbered="true" toc="default"> | |||
> | <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 | |||
a valid designation of that revoked state until | a valid designation of that revoked state until | |||
the client frees it by using FREE_STATEID. | the client frees it by using FREE_STATEID. | |||
Stateids associated | Stateids associated | |||
with byte-range locks are an exception. They remain valid even | with byte-range locks are an exception. They remain valid even | |||
if a LOCKU frees all remaining locks, so long as the open file | if a LOCKU frees all remaining locks, so long as the open file | |||
with which they are associated remains open, unless the client | with which they are associated remains open, unless the client | |||
frees the stateids via the FREE_STATEID operation. | frees the stateids via the FREE_STATEID operation. | |||
</t> | </t> | |||
<t> | <t> | |||
It should be noted that there are situations in which the | It should be noted that there are situations in which the | |||
client's locks become invalid, without the client requesting | client's locks become invalid, without the client requesting | |||
they be returned. These include lease expiration and a number | they be returned. These include lease expiration and a number | |||
of forms of lock revocation within the lease period. It is | of forms of lock revocation within the lease period. It is | |||
important to note that in these situations, the stateid remains | important to note that in these situations, the stateid remains | |||
valid and the client can use it to determine the disposition of | valid and the client can use it to determine the disposition of | |||
the associated lost locks. | the associated lost locks. | |||
</t> | </t> | |||
<t> | <t> | |||
An "other" value must never be reused for a different purpose | An "other" value must never be reused for a different purpose | |||
(i.e., different filehandle, owner, or type of locks) within the | (i.e., different filehandle, owner, or type of locks) within the | |||
context of a single client ID. A server may retain the "other" | context of a single client ID. A server may retain the "other" | |||
value for the same purpose beyond the point where it may otherwise | value for the same purpose beyond the point where it may otherwise | |||
be freed, but if it does so, it must maintain "seqid" continuity | be freed, but if it does so, it must maintain "seqid" continuity | |||
with previous values. | with previous values. | |||
</t> | </t> | |||
<t> | <t> | |||
One mechanism that may be used to satisfy the requirement that the | One mechanism that may be used to satisfy the requirement that the | |||
server recognize invalid and out-of-date stateids is for | server recognize invalid and out-of-date stateids is for | |||
the server to divide the "other" field of the stateid into two | the server to divide the "other" field of the stateid into two | |||
fields. | fields. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
an index into a table of locking-state structures. | an index into a table of locking-state structures. | |||
</t> | </li> | |||
<t> | <li> | |||
a generation number that is incremented on each allocation | a generation number that is incremented on each allocation | |||
of a table entry for a particular use. | of a table entry for a particular use. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
And then store in each table entry, | And then store in each table entry, | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
the client ID with which the stateid is associated. | the client ID with which the stateid is associated. | |||
</t> | </li> | |||
<t> | <li> | |||
the current generation number for the (at most one) | the current generation number for the (at most one) | |||
valid stateid sharing this index value. | valid stateid sharing this index value. | |||
</t> | </li> | |||
<t> | <li> | |||
the filehandle of the file on which the locks are taken. | the filehandle of the file on which the locks are taken. | |||
</t> | </li> | |||
<t> | <li> | |||
an indication of the type of stateid (open, byte-range lock, | an indication of the type of stateid (open, byte-range lock, | |||
file delegation, directory delegation, layout). | file delegation, directory delegation, layout). | |||
</t> | </li> | |||
<t> | <li> | |||
the last "seqid" value returned corresponding to the current | the last "seqid" value returned corresponding to the current | |||
"other" value. | "other" value. | |||
</t> | </li> | |||
<t> | <li> | |||
an indication of the current status of the locks | an indication of the current status of the locks | |||
associated with this stateid, in particular, | associated with this stateid, in particular, | |||
whether these have been revoked and if so, for what reason. | whether these have been revoked and if so, for what reason. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
With this information, an incoming stateid can be validated and | With this information, an incoming stateid can be validated and | |||
the appropriate error returned when necessary. Special and | the appropriate error returned when necessary. Special and | |||
non-special stateids are handled separately. (See | non-special stateids are handled separately. (See | |||
<xref target='special_stateid' /> for a discussion of special | <xref target="special_stateid" format="default"/> for a discussion of special | |||
stateids.) | stateids.) | |||
</t> | </t> | |||
<t> | <t> | |||
Note that stateids are implicitly qualified by the current client | Note that stateids are implicitly qualified by the current client | |||
ID, as derived from the client ID associated with the current | ID, as derived from the client ID associated with the current | |||
session. Note, however, that the semantics of the session will | session. Note, however, that the semantics of the session will | |||
prevent stateids associated with a previous client or server | prevent stateids associated with a previous client or server | |||
instance from being analyzed by this procedure. | instance from being analyzed by this procedure. | |||
</t> | </t> | |||
<t> | <t> | |||
If server restart has resulted in an invalid | If server restart has resulted in an invalid | |||
client ID or a session ID that is invalid, SEQUENCE will return | client ID or a session ID that is invalid, SEQUENCE will return | |||
an error and the operation that takes a stateid as an argument will ne ver | an error and the operation that takes a stateid as an argument will ne ver | |||
be processed. | be processed. | |||
</t> | </t> | |||
<t> | <t> | |||
If there has been a server restart where there is a persistent | If there has been a server restart where there is a persistent | |||
session and all leased state has been lost, then the session | session and all leased state has been lost, then the session | |||
in question will, although valid, be marked as dead, and any | in question will, although valid, be marked as dead, and any | |||
operation not satisfied by means of the reply cache will | operation not satisfied by means of the reply cache will | |||
receive the error NFS4ERR_DEADSESSION, and thus not be | receive the error NFS4ERR_DEADSESSION, and thus not be | |||
processed as indicated below. | processed as indicated below. | |||
</t> | </t> | |||
<t> | <t> | |||
When a stateid is being tested and the "other" field is all | When a stateid is being tested and the "other" field is all | |||
zeros or all ones, a check that | zeros or all ones, a check that | |||
the "other" and "seqid" fields match a defined combination for | the "other" and "seqid" fields match a defined combination for | |||
a special stateid is done and the results determined as follows: | a special stateid is done and the results determined as follows: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If the "other" and "seqid" fields do not match a defined | If the "other" and "seqid" fields do not match a defined | |||
combination associated with a special stateid, the error | combination associated with a special stateid, the error | |||
NFS4ERR_BAD_STATEID is returned. | NFS4ERR_BAD_STATEID is returned. | |||
</t> | </li> | |||
<t> | <li> | |||
If the special stateid is one designating the current | If the special stateid is one designating the current | |||
stateid and there is a current stateid, then the current | stateid and there is a current stateid, then the current | |||
stateid is substituted for the special stateid and the | stateid is substituted for the special stateid and the | |||
checks appropriate to non-special stateids are performed. | checks appropriate to non-special stateids are performed. | |||
</t> | </li> | |||
<t> | <li> | |||
If the combination is valid in general but is not | If the combination is valid in general but is not | |||
appropriate to the context in which the stateid is used | appropriate to the context in which the stateid is used | |||
(e.g., an all-zero stateid is used when an OPEN stateid | (e.g., an all-zero stateid is used when an OPEN stateid | |||
is required in a LOCK operation), the error | is required in a LOCK operation), the error | |||
NFS4ERR_BAD_STATEID is also returned. | NFS4ERR_BAD_STATEID is also returned. | |||
</t> | </li> | |||
<t> | <li> | |||
Otherwise, the check is completed and the special stateid | Otherwise, the check is completed and the special stateid | |||
is accepted as valid. | is accepted as valid. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
When a stateid is being tested, | When a stateid is being tested, | |||
and the "other" field is neither all zeros nor all ones, the | and the "other" field is neither all zeros nor all ones, the | |||
following procedure could be used to | following procedure could be used to | |||
validate an incoming stateid and return an appropriate error, | validate an incoming stateid and return an appropriate error, | |||
when necessary, assuming that the "other" field would be divided | when necessary, assuming that the "other" field would be divided | |||
into a table index and an entry generation. | into a table index and an entry generation. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If the table index field is outside the range of the | If the table index field is outside the range of the | |||
associated table, return NFS4ERR_BAD_STATEID. | associated table, return NFS4ERR_BAD_STATEID. | |||
</t> | </li> | |||
<t> | <li> | |||
If the selected table entry is of a different generation than | If the selected table entry is of a different generation than | |||
that specified in the incoming stateid, return | that specified in the incoming stateid, return | |||
NFS4ERR_BAD_STATEID. | NFS4ERR_BAD_STATEID. | |||
</t> | </li> | |||
<t> | <li> | |||
If the selected table entry does not match the current | If the selected table entry does not match the current | |||
filehandle, return NFS4ERR_BAD_STATEID. | filehandle, return NFS4ERR_BAD_STATEID. | |||
</t> | </li> | |||
<t> | <li> | |||
If the client ID in the table entry does not match the | If the client ID in the table entry does not match the | |||
client ID associated with the current session, | client ID associated with the current session, | |||
return NFS4ERR_BAD_STATEID. | return NFS4ERR_BAD_STATEID. | |||
</t> | </li> | |||
<t> | <li> | |||
If the stateid represents revoked state, then return | If the stateid represents revoked state, then return | |||
NFS4ERR_EXPIRED, NFS4ERR_ADMIN_REVOKED, or | NFS4ERR_EXPIRED, NFS4ERR_ADMIN_REVOKED, or | |||
NFS4ERR_DELEG_REVOKED, as appropriate. | NFS4ERR_DELEG_REVOKED, as appropriate. | |||
</t> | </li> | |||
<t> | <li> | |||
If the stateid type is not valid for the context in which the | If the stateid type is not valid for the context in which the | |||
stateid appears, return NFS4ERR_BAD_STATEID. | stateid appears, return NFS4ERR_BAD_STATEID. | |||
Note that a stateid may be valid in general, as would be | Note that a stateid may be valid in general, as would be | |||
reported by the TEST_STATEID operation, but be invalid for | reported by the TEST_STATEID operation, but be invalid for | |||
a particular operation, as, for example, when a stateid | a particular operation, as, for example, when a stateid | |||
that doesn't represent byte-range locks is passed to | that doesn't represent byte-range locks is passed to | |||
the non-from_open case of LOCK or to LOCKU, or when a stateid | the non-from_open case of LOCK or to LOCKU, or when a stateid | |||
that does not represent an open is passed to CLOSE or | that does not represent an open is passed to CLOSE or | |||
OPEN_DOWNGRADE. In such cases, the server MUST return | OPEN_DOWNGRADE. In such cases, the server <bcp14>MUST</bcp14> ret urn | |||
NFS4ERR_BAD_STATEID. | NFS4ERR_BAD_STATEID. | |||
</t> | </li> | |||
<t> | <li> | |||
If the "seqid" field is not zero and it is greater | If the "seqid" field is not zero and it is greater | |||
than the current sequence value corresponding to the | than the current sequence value corresponding to the | |||
current "other" field, return NFS4ERR_BAD_STATEID. | current "other" field, return NFS4ERR_BAD_STATEID. | |||
</t> | </li> | |||
<t> | <li> | |||
If the "seqid" field is not zero and it is less | If the "seqid" field is not zero and it is less | |||
than the current sequence value corresponding to the | than the current sequence value corresponding to the | |||
current "other" field, return NFS4ERR_OLD_STATEID. | current "other" field, return NFS4ERR_OLD_STATEID. | |||
</t> | </li> | |||
<t> | <li> | |||
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. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> <!-- "Stateid Lifetime and Validation" --> | <section anchor="stateid_use" numbered="true" toc="default"> | |||
<section anchor="stateid_use" title="Stateid Use for I/O Operations"> | <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> | |||
<t> | <t> | |||
The following rules, applied in order of decreasing priority, | The following rules, applied in order of decreasing priority, | |||
govern the selection of the appropriate stateid. In following | govern the selection of the appropriate stateid. In following | |||
these rules, the client will only consider locks of which it | these rules, the client will only consider locks of which it | |||
has actually received notification by an appropriate operation | has actually received notification by an appropriate operation | |||
response or callback. Note that the | response or callback. Note that the | |||
rules are slightly different in the case of I/O to data servers | rules are slightly different in the case of I/O to data servers | |||
when file layouts are being | when file layouts are being | |||
used (see <xref target="global_stateid" />). | used (see <xref target="global_stateid" format="default"/>). | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If the client holds a delegation for the file in question, the | If the client holds a delegation for the file in question, the | |||
delegation stateid SHOULD be used. | delegation stateid <bcp14>SHOULD</bcp14> be used. | |||
</t> | </li> | |||
<t> | <li> | |||
Otherwise, if the entity corresponding to the lock-owner (e.g., a process) | Otherwise, if the entity corresponding to the lock-owner (e.g., a process) | |||
sending the I/O has a byte-range lock stateid for the associated o pen file, | sending the I/O has a byte-range lock stateid for the associated o pen file, | |||
then the byte-range lock stateid for that lock-owner and open file SHOULD | then the byte-range lock stateid for that lock-owner and open file <bcp14>SHOULD</bcp14> | |||
be used. | be used. | |||
</t> | </li> | |||
<t> | <li> | |||
If there is no byte-range lock stateid, then the OPEN stateid for the open | If there is no byte-range lock stateid, then the OPEN stateid for the open | |||
file in question SHOULD be used. | file in question <bcp14>SHOULD</bcp14> be used. | |||
</t> | </li> | |||
<t> | <li> | |||
Finally, if none of the above apply, then a special stateid | Finally, if none of the above apply, then a special stateid | |||
SHOULD be used. | <bcp14>SHOULD</bcp14> be used. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Ignoring these rules may result in situations in which the server | Ignoring these rules may result in situations in which the server | |||
does not have information necessary to properly process the request. | does not have information necessary to properly process the request. | |||
For example, when mandatory byte-range locks are in effect, if the | For example, when mandatory byte-range locks are in effect, if the | |||
stateid does not indicate the proper lock-owner, via a lock stateid, | stateid does not indicate the proper lock-owner, via a lock stateid, | |||
a request might be avoidably rejected. | a request might be avoidably rejected. | |||
</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 give n file, it | I/O requests. In particular, when a client has a delegation for a give n file, it | |||
SHOULD 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> <!-- "Stateid Use for I/O Operations" --> | </section> | |||
<section anchor="stateid_use_sa" title="Stateid Use for SETATTR Operations | <section anchor="stateid_use_sa" numbered="true" toc="default"> | |||
"> | <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 SHOULD 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 SHOULD note the presence of | as to whether a delegation is held, it <bcp14>SHOULD</bcp14> note the | |||
a delegation even when a special stateid is sent, and MUST accept a | presence of | |||
a delegation even when a special stateid is sent, and <bcp14>MUST</bcp | ||||
14> accept a | ||||
valid delegation stateid when sent. | valid delegation stateid when sent. | |||
</t> | </t> | |||
</section> <!-- "Stateid Use for SETATTR Operations" --> | </section> | |||
</section> <!-- "Stateid Definition" --> | </section> | |||
<section anchor="lease_renewal" title="Lease Renewal" > | <section anchor="lease_renewal" numbered="true" toc="default"> | |||
<t> | <name>Lease Renewal</name> | |||
<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 | |||
unreachable, once the relevant lease expires. This in turn allows | unreachable, once the relevant lease expires. This in turn allows | |||
other clients to obtain conflicting locks without being | other clients to obtain conflicting locks without being | |||
delayed indefinitely by inactive or unreachable clients. | delayed indefinitely by inactive or unreachable clients. | |||
It is not a | It is not a | |||
mechanism for cache consistency and lease | mechanism for cache consistency and lease | |||
renewals may not be denied if the lease interval has not expired. | renewals may not be denied if the lease interval has not expired. | |||
</t> | </t> | |||
<t> | <t> | |||
Since each session is associated with a specific | Since each session is associated with a specific | |||
client (identified by the client's client ID), any | client (identified by the client's client ID), any | |||
operation sent on that session is an indication | operation sent on that session is an indication | |||
that the associated client is reachable. When a | that the associated client is reachable. When a | |||
request is sent for a given session, successful | request is sent for a given session, successful | |||
execution of a SEQUENCE operation (or successful | execution of a SEQUENCE operation (or successful | |||
retrieval of the result of SEQUENCE from the reply | retrieval of the result of SEQUENCE from the reply | |||
cache) on an unexpired lease will result in the | cache) on an unexpired lease will result in the | |||
lease being implicitly renewed, for the standard | lease being implicitly renewed, for the standard | |||
renewal period (equal to the lease_time attribute). | renewal period (equal to the lease_time attribute). | |||
</t> | </t> | |||
<t> | <t> | |||
If the client ID's lease has not expired when the | If the client ID's lease has not expired when the | |||
server receives a SEQUENCE operation, then the server | server receives a SEQUENCE operation, then the server | |||
MUST renew the lease. If the client ID's lease has expired | <bcp14>MUST</bcp14> renew the lease. If the client ID's lease has expired | |||
when the server receives a SEQUENCE operation, the | when the server receives a SEQUENCE operation, the | |||
server MAY renew the lease; this depends on whether | server <bcp14>MAY</bcp14> renew the lease; this depends on whether | |||
any state was revoked as a result of the client's | any state was revoked as a result of the client's | |||
failure to renew the lease before expiration. | failure to renew the lease before expiration. | |||
</t> | </t> | |||
<t> | <t> | |||
Absent other activity that would renew the lease, a COMPOUND | Absent other activity that would renew the lease, a COMPOUND | |||
consisting of a single SEQUENCE operation will suffice. The | consisting of a single SEQUENCE operation will suffice. The | |||
client should also take communication-related delays into | client should also take communication-related delays into | |||
account and take steps to ensure that the renewal messages | account and take steps to ensure that the renewal messages | |||
actually reach the server in good time. For example: | actually reach the server in good time. For example: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
When trunking is in effect, the client should | When trunking is in effect, the client should | |||
consider sending multiple requests on different | consider sending multiple requests on different | |||
connections, in order to ensure that renewal | connections, in order to ensure that renewal | |||
occurs, even in the event of blockage in the | occurs, even in the event of blockage in the | |||
path used for one of those connections. | path used for one of those connections. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
Transport retransmission delays might become | Transport retransmission delays might become | |||
so large as to approach or exceed the length | so large as to approach or exceed the length | |||
of the lease period. This may be particularly | of the lease period. This may be particularly | |||
likely when the server is unresponsive due to | likely when the server is unresponsive due to | |||
a restart; see <xref target="reclaim_locks" | a restart; see <xref target="reclaim_locks" format="default"/>. If the | |||
/>. If the client implementation is not careful, | client implementation is not careful, | |||
transport retransmission delays can result in the | transport retransmission delays can result in the | |||
client failing to detect a server restart before | client failing to detect a server restart before | |||
the grace period ends. The scenario is that the | the grace period ends. The scenario is that the | |||
client is using a transport with exponential | client is using a transport with exponential | |||
backoff, such that the maximum retransmission | backoff, such that the maximum retransmission | |||
timeout exceeds both the grace period and the | timeout exceeds both the grace period and the | |||
lease_time attribute. A network partition causes | lease_time attribute. A network partition causes | |||
the client's connection's retransmission interval | the client's connection's retransmission interval | |||
to back off, and even after the partition heals, | to back off, and even after the partition heals, | |||
the next transport-level retransmission is sent | the next transport-level retransmission is sent | |||
after the server has restarted and its grace | after the server has restarted and its grace | |||
period ends. | period ends. | |||
<vspace blankLines="1" /> | </t> | |||
<t> | ||||
The client MUST either recover from the ensuing | The client <bcp14>MUST</bcp14> either recover from the ensuing | |||
NFS4ERR_NO_GRACE errors or it MUST ensure that, | NFS4ERR_NO_GRACE errors or it <bcp14>MUST</bcp14> ensure that, | |||
despite transport-level retransmission intervals | despite transport-level retransmission intervals | |||
that exceed the lease_time, a SEQUENCE operation is sent | that exceed the lease_time, a SEQUENCE operation is sent | |||
that renews the lease before expiration. The client can achieve this | that renews the lease before expiration. The client can achieve this | |||
by associating a new connection with the session, | by associating a new connection with the session, | |||
and sending a SEQUENCE operation on it. However, if | and sending a SEQUENCE operation on it. However, if | |||
the attempt to establish a new connection is delayed | the attempt to establish a new connection is delayed | |||
for some reason (e.g., exponential backoff of the connection | for some reason (e.g., exponential backoff of the connection | |||
establishment packets), the client will have to | establishment packets), the client will have to | |||
abort the connection establishment attempt before | abort the connection establishment attempt before | |||
the lease expires, and attempt to reconnect. | the lease expires, and attempt to reconnect. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ul> | |||
<t> | <t> | |||
If the server renews the lease upon receiving | If the server renews the lease upon receiving | |||
a SEQUENCE operation, the server MUST NOT allow the lease | a SEQUENCE operation, the server <bcp14>MUST NOT</bcp14> allow the lease | |||
to expire while the rest of the operations | to expire while the rest of the operations | |||
in the COMPOUND procedure's request are still | in the COMPOUND procedure's request are still | |||
executing. Once the last operation has finished, and | executing. Once the last operation has finished, and | |||
the response to COMPOUND has been sent, the server | the response to COMPOUND has been sent, the server | |||
MUST set the lease to expire no sooner than the | <bcp14>MUST</bcp14> set the lease to expire no sooner than the | |||
sum of current time and the value of the lease_time attribute. | sum of current time and the value of the lease_time attribute. | |||
</t> | </t> | |||
<t> | <t> | |||
A client ID's lease can expire when it has been | A client ID's lease can expire when it has been | |||
at least the lease interval (lease_time) since the | at least the lease interval (lease_time) since the | |||
last lease-renewing SEQUENCE operation was sent | last lease-renewing SEQUENCE operation was sent | |||
on any of the client ID's sessions and there | on any of the client ID's sessions and there | |||
are no active COMPOUND operations on any such sessions. | are no active COMPOUND operations on any such sessions. | |||
</t> | </t> | |||
<t> | <t> | |||
Because the SEQUENCE operation is the basic mechanism to renew | Because the SEQUENCE operation is the basic mechanism to renew | |||
a lease, and because it must be done at least once for each | a lease, and because it must be done at least once for each | |||
lease period, it is the natural mechanism whereby the server | lease period, it is the natural mechanism whereby the server | |||
will inform the client of changes in the lease status that the | will inform the client of changes in the lease status that the | |||
client needs to be informed of. The client should inspect the | client needs to be informed of. The client should inspect the | |||
status flags (sr_status_flags) returned by sequence and take | status flags (sr_status_flags) returned by sequence and take | |||
the appropriate action (see | the appropriate action (see | |||
<xref target="OP_SEQUENCE_DESCRIPTION" /> for details). | <xref target="OP_SEQUENCE_DESCRIPTION" format="default"/> for details). | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The status bits SEQ4_STATUS_CB_PATH_DOWN and | The status bits SEQ4_STATUS_CB_PATH_DOWN and | |||
SEQ4_STATUS_CB_PATH_DOWN_SESSION indicate problems with | SEQ4_STATUS_CB_PATH_DOWN_SESSION indicate problems with | |||
the backchannel that the client may need to address | the backchannel that the client may need to address | |||
in order to receive callback requests. | in order to receive callback requests. | |||
</t> | </li> | |||
<t> | <li> | |||
The status bits SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRING and | The status bits SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRING and | |||
SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRED indicate | SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRED indicate | |||
problems with GSS contexts or RPCSEC_GSS handles | problems with GSS contexts or RPCSEC_GSS handles | |||
for the backchannel that the | for the backchannel that the | |||
client might have to address in order to allow callback requests | client might have to address in order to allow callback requests | |||
to be sent. | to be sent. | |||
</t> | </li> | |||
<t> | <li> | |||
The status bits SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED, | The status bits SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED, | |||
SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED, | SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED, | |||
SEQ4_STATUS_ADMIN_STATE_REVOKED, and | SEQ4_STATUS_ADMIN_STATE_REVOKED, and | |||
SEQ4_STATUS_RECALLABLE_STATE_REVOKED notify the | SEQ4_STATUS_RECALLABLE_STATE_REVOKED notify the | |||
client of lock revocation events. When these bits | client of lock revocation events. When these bits | |||
are set, the client should use TEST_STATEID to find | are set, the client should use TEST_STATEID to find | |||
what stateids have been revoked and use FREE_STATEID | what stateids have been revoked and use FREE_STATEID | |||
to acknowledge loss of the associated state. | to acknowledge loss of the associated state. | |||
</t> | </li> | |||
<t> | <li> | |||
The status bit SEQ4_STATUS_LEASE_MOVE | The status bit SEQ4_STATUS_LEASE_MOVE | |||
indicates that | indicates that | |||
responsibility for lease renewal has been transferred to | responsibility for lease renewal has been transferred to | |||
one or more new servers. | one or more new servers. | |||
</t> | </li> | |||
<t> | <li> | |||
The status bit SEQ4_STATUS_RESTART_RECLAIM_NEEDED | The status bit SEQ4_STATUS_RESTART_RECLAIM_NEEDED | |||
indicates that due to server | indicates that due to server | |||
restart the client must reclaim locking state. | restart the client must reclaim locking state. | |||
</t> | </li> | |||
<t> | <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). | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> <!-- "Lease Renewal" --> | <section anchor="lock_crash_recovery" numbered="true" toc="default"> | |||
<section title="Crash Recovery" anchor="lock_crash_recovery" > | <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 | |||
server before the server can safely determine that the client | server before the server can safely determine that the client | |||
has recovered enough locking state to be sure that such | has recovered enough locking state to be sure that such | |||
operations can be safely processed must be rejected. | operations can be safely processed must be rejected. | |||
This will happen because either: | This will happen because either: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The state presented is no longer valid since it is | The state presented is no longer valid since it is | |||
associated with a now invalid client ID. In this case, the | associated with a now invalid client ID. In this case, the | |||
client will receive either an NFS4ERR_BADSESSION or | client will receive either an NFS4ERR_BADSESSION or | |||
NFS4ERR_DEADSESSION error, and any attempt to attach a new | NFS4ERR_DEADSESSION error, and any attempt to attach a new | |||
session to that invalid client ID will result in an | session to that invalid client ID will result in an | |||
NFS4ERR_STALE_CLIENTID error. | NFS4ERR_STALE_CLIENTID error. | |||
</t> | </li> | |||
<t> | <li> | |||
Subsequent recovery of locks may make execution of the | Subsequent recovery of locks may make execution of the | |||
operation inappropriate (NFS4ERR_GRACE). | operation inappropriate (NFS4ERR_GRACE). | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <section numbered="true" toc="default"> | |||
<section title="Client Failure and Recovery" > | <name>Client Failure and Recovery</name> | |||
<t> | <t> | |||
In the event that a client fails, the server may release the | In the event that a client fails, the server may release the | |||
client's locks when the associated lease has expired. Conflicting | client's locks when the associated lease has expired. Conflicting | |||
locks from another client may only be granted after this lease | locks from another client may only be granted after this lease | |||
expiration. As discussed in <xref target="lease_renewal" />, when | expiration. As discussed in <xref target="lease_renewal" format="defaul t"/>, when | |||
a client has not failed and re-establishes its lease before expiration | a client has not failed and re-establishes its lease before expiration | |||
occurs, requests for conflicting locks will not be granted. | occurs, requests for conflicting locks will not be granted. | |||
</t> | </t> | |||
<t> | <t> | |||
To minimize client delay upon restart, lock requests are associated | To minimize client delay upon restart, lock requests are associated | |||
with an instance of the client by a client-supplied verifier. This | with an instance of the client by a client-supplied verifier. This | |||
verifier is part of the client_owner4 sent in the initial | verifier is part of the client_owner4 sent in the initial | |||
EXCHANGE_ID call made by the client. | EXCHANGE_ID call made by the client. | |||
The server returns a client ID as a result of the EXCHANGE_ID | The server returns a client ID as a result of the EXCHANGE_ID | |||
operation. The client then confirms the use of the client ID by | operation. The client then confirms the use of the client ID by | |||
establishing a session associated with that client ID (see | establishing a session associated with that client ID (see | |||
<xref target='OP_CREATE_SESSION_DESCRIPTION' /> for a | <xref target="OP_CREATE_SESSION_DESCRIPTION" format="default"/> for a | |||
description of how this is done). All locks, | description of how this is done). All locks, | |||
including opens, byte-range locks, delegations, and layouts obtained | including opens, byte-range locks, delegations, and layouts obtained | |||
by sessions using that client ID, are associated with that client ID. | by sessions using that client ID, are associated with that client ID. | |||
</t> | </t> | |||
<t> | <t> | |||
Since the verifier will be changed by the client upon each | Since the verifier will be changed by the client upon each | |||
initialization, the server can compare a new verifier to the verifier | initialization, the server can compare a new verifier to the verifier | |||
associated with currently held locks and determine that they do not | associated with currently held locks and determine that they do not | |||
match. This signifies the client's new instantiation and subsequent | match. This signifies the client's new instantiation and subsequent | |||
loss (upon confirmation of the new client ID) of locking | loss (upon confirmation of the new client ID) of locking | |||
state. As a result, the server is free to release all | state. As a result, the server is free to release all | |||
locks held that are associated with the old client ID that was | locks held that are associated with the old client ID that was | |||
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> <!-- "Client Failure and Recovery" --> | </section> | |||
<section anchor="server_failure" title="Server Failure and Recovery" > | <section anchor="server_failure" numbered="true" toc="default"> | |||
<t> | <name>Server Failure and Recovery</name> | |||
<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 | |||
WRITE operations. For example, if mandatory locks are a possibility, | WRITE operations. For example, if mandatory locks are a possibility, | |||
the server must disallow READ and WRITE operations for that file. | the server must disallow READ and WRITE operations for that file. | |||
</t> | </t> | |||
<t> | <t> | |||
A client can determine that loss of locking | A client can determine that loss of locking | |||
state has occurred via several methods. | state has occurred via several methods. | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
When a SEQUENCE (most common) or other operation returns | When a SEQUENCE (most common) or other operation returns | |||
NFS4ERR_BADSESSION, this may mean that the session has | NFS4ERR_BADSESSION, this may mean that the session has | |||
been destroyed but the client ID is still valid. | been destroyed but the client ID is still valid. | |||
The client sends a CREATE_SESSION request with the | The client sends a CREATE_SESSION request with the | |||
client ID to re-establish the session. If | client ID to re-establish the session. If | |||
CREATE_SESSION fails with NFS4ERR_STALE_CLIENTID, | CREATE_SESSION fails with NFS4ERR_STALE_CLIENTID, | |||
the client must establish a new client ID (see | the client must establish a new client ID (see | |||
<xref target="client_id" />) and re-establish its | <xref target="client_id" format="default"/>) and re-establish its | |||
lock state with the new client ID, after the CREATE_SESSION | lock state with the new client ID, after the CREATE_SESSION | |||
operation succeeds (see <xref target="reclaim_locks" />). | operation succeeds (see <xref target="reclaim_locks" format="default"/>) . | |||
</t> | </li> | |||
<t> | <li> | |||
When a SEQUENCE (most common) or other operation on a | When a SEQUENCE (most common) or other operation on a | |||
persistent session returns NFS4ERR_DEADSESSION, this indicates | persistent session returns NFS4ERR_DEADSESSION, this indicates | |||
that a session is no longer usable for new, i.e., not satisfied | that a session is no longer usable for new, i.e., not satisfied | |||
from the reply cache, operations. Once all pending operations | from the reply cache, operations. Once all pending operations | |||
are determined to be either performed before the retry or not | are determined to be either performed before the retry or not | |||
performed, the client sends a CREATE_SESSION request with the | performed, the client sends a CREATE_SESSION request with the | |||
client ID to re-establish the session. If | client ID to re-establish the session. If | |||
CREATE_SESSION fails with NFS4ERR_STALE_CLIENTID, | CREATE_SESSION fails with NFS4ERR_STALE_CLIENTID, | |||
the client must establish a new client ID (see | the client must establish a new client ID (see | |||
<xref target="client_id" />) and re-establish its | <xref target="client_id" format="default"/>) and re-establish its | |||
lock state after the CREATE_SESSION, with the | lock state after the CREATE_SESSION, with the | |||
new client ID, succeeds | new client ID, succeeds | |||
(<xref target="reclaim_locks" />). | (<xref target="reclaim_locks" format="default"/>). | |||
</t> | </li> | |||
<t> | <li> | |||
When an operation, neither SEQUENCE nor preceded by SEQUENCE (for | When an operation, neither SEQUENCE nor preceded by SEQUENCE (for | |||
example, CREATE_SESSION, DESTROY_SESSION), returns | example, CREATE_SESSION, DESTROY_SESSION), returns | |||
NFS4ERR_STALE_CLIENTID, the client MUST establish | NFS4ERR_STALE_CLIENTID, the client <bcp14>MUST</bcp14> establish | |||
a new client ID (<xref target="client_id" />) and | a new client ID (<xref target="client_id" format="default"/>) and | |||
re-establish its lock state (<xref | re-establish its lock state (<xref target="reclaim_locks" format="default | |||
target="reclaim_locks" />). | "/>). | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | <section anchor="reclaim_locks" numbered="true" toc="default"> | |||
<section anchor="reclaim_locks" title="State Reclaim" > | <name>State Reclaim</name> | |||
<t> | <t> | |||
When state information and the associated locks are lost | When state information and the associated locks are lost | |||
as a result of a server restart, the protocol must provide | as a result of a server restart, the protocol must provide | |||
a way to cause that state to be re-established. The | a way to cause that state to be re-established. The | |||
approach used is to define, for most types of locking | approach used is to define, for most types of locking | |||
state (layouts are an exception), a request whose function | state (layouts are an exception), a request whose function | |||
is to allow the client to | is to allow the client to | |||
re-establish on the server a lock first obtained from a | re-establish on the server a lock first obtained from a | |||
previous instance. Generally, these requests are variants | previous instance. Generally, these requests are variants | |||
of the requests normally used to create locks of that type | of the requests normally used to create locks of that type | |||
and are referred to as "reclaim-type" requests, and the process | and are referred to as "reclaim-type" requests, and the process | |||
of re-establishing such locks is referred to as "reclaiming" | of re-establishing such locks is referred to as "reclaiming" | |||
them. | them. | |||
</t> | </t> | |||
<t anchor="read_write_grace"> | <t anchor="read_write_grace"> | |||
Because each client must have an opportunity to reclaim | Because each client must have an opportunity to reclaim | |||
all of the locks that it has without the possibility that | all of the locks that it has without the possibility that | |||
some other client will be granted a conflicting lock, | some other client will be granted a conflicting lock, | |||
a "grace period" is devoted | a "grace period" is devoted | |||
to the reclaim process. During this period, requests | to the reclaim process. During this period, requests | |||
creating client IDs and | creating client IDs and | |||
sessions are handled normally, but locking requests are | sessions are handled normally, but locking requests are | |||
subject to special restrictions. Only | subject to special restrictions. Only | |||
reclaim-type locking requests are allowed, unless the | reclaim-type locking requests are allowed, unless the | |||
server can reliably determine (through state | server can reliably determine (through state | |||
persistently maintained across restart instances) that | persistently maintained across restart instances) that | |||
granting any such lock cannot possibly conflict with a | granting any such lock cannot possibly conflict with a | |||
subsequent reclaim. | subsequent reclaim. | |||
When a request is made to obtain | When a request is made to obtain | |||
a new lock (i.e., not a reclaim-type request) during the | a new lock (i.e., not a reclaim-type request) during the | |||
grace period and such a determination cannot be made, | grace period and such a determination cannot be made, | |||
the server must return the error NFS4ERR_GRACE. | the server must return the error NFS4ERR_GRACE. | |||
</t> | </t> | |||
<t> | <t> | |||
Once a session is established using the new client ID, the | Once a session is established using the new client ID, the | |||
client will use reclaim-type locking requests (e.g., LOCK | client will use reclaim-type locking requests (e.g., LOCK | |||
operations with reclaim set to TRUE and OPEN operations with a | operations with reclaim set to TRUE and OPEN operations with a | |||
claim type of CLAIM_PREVIOUS; see | claim type of CLAIM_PREVIOUS; see | |||
<xref target="open_br_reclaim" />) to re-establish its locking | <xref target="open_br_reclaim" format="default"/>) to re-establish its l ocking | |||
state. Once this is done, or if there is no such locking | state. Once this is done, or if there is no such locking | |||
state to reclaim, the client sends a global RECLAIM_COMPLETE | state to reclaim, the client sends a global RECLAIM_COMPLETE | |||
operation, i.e., one with the rca_one_fs argument set to FALSE, to | operation, i.e., one with the rca_one_fs argument set to FALSE, to | |||
indicate that it has reclaimed all of the locking state that | indicate that it has reclaimed all of the locking state that | |||
it will reclaim. Once a client sends such a RECLAIM_COMPLETE | it will reclaim. Once a client sends such a RECLAIM_COMPLETE | |||
operation, it may attempt non-reclaim locking operations, | operation, it may attempt non-reclaim locking operations, | |||
although it might get an NFS4ERR_GRACE status result from each such oper ation until | although it might get an NFS4ERR_GRACE status result from each such oper ation until | |||
the period of special handling is over. | the period of special handling is over. | |||
See <xref target="SEC11-EFF-lock" /> for a discussion of the | See <xref target="SEC11-EFF-lock" format="default"/> for a discussion of the | |||
analogous handling lock reclamation in the case of file systems | analogous handling lock reclamation in the case of file systems | |||
transitioning from server to server. | transitioning from server to server. | |||
</t> | </t> | |||
<t> | <t> | |||
During the grace period, the server must reject READ | During the grace period, the server must reject READ | |||
and WRITE operations | and WRITE operations | |||
and non-reclaim locking requests (i.e., other LOCK | and non-reclaim locking requests (i.e., other LOCK | |||
and OPEN operations) with an error of NFS4ERR_GRACE, | and OPEN operations) with an error of NFS4ERR_GRACE, | |||
unless it can guarantee that these may be done | unless it can guarantee that these may be done | |||
safely, as described below. | safely, as described below. | |||
</t> | </t> | |||
<t> | <t> | |||
The grace period may last until all clients that are known to | The grace period may last until all clients that are known to | |||
possibly have had locks have done a global RECLAIM_COMPLETE operation, i ndicating | possibly have had locks have done a global RECLAIM_COMPLETE operation, i ndicating | |||
that they have finished reclaiming the locks they held before | that they have finished reclaiming the locks they held before | |||
the server restart. This means that a client that has done a | the server restart. This means that a client that has done a | |||
RECLAIM_COMPLETE must be prepared to receive an NFS4ERR_GRACE | RECLAIM_COMPLETE must be prepared to receive an NFS4ERR_GRACE | |||
when attempting to acquire new locks. | when attempting to acquire new locks. | |||
In order for the server to know that all clients with possible prior | In order for the server to know that all clients with possible prior | |||
lock state have done a RECLAIM_COMPLETE, | lock state have done a RECLAIM_COMPLETE, | |||
the server must maintain in stable | the server must maintain in stable | |||
storage a list clients that may have such locks. The server | storage a list clients that may have such locks. The server | |||
may also terminate the grace period before all clients have | may also terminate the grace period before all clients have | |||
done a global RECLAIM_COMPLETE. The server SHOULD NOT terminate the | done a global RECLAIM_COMPLETE. The server <bcp14>SHOULD NOT</bcp14> te rminate the | |||
grace period before a time equal to the lease period in order | grace period before a time equal to the lease period in order | |||
to give clients an opportunity to find out about the server | to give clients an opportunity to find out about the server | |||
restart, as a result of sending requests on associated | restart, as a result of sending requests on associated | |||
sessions with a frequency governed by the lease time. | sessions with a frequency governed by the lease time. | |||
Note that when a client does not send such requests (or they | Note that when a client does not send such requests (or they | |||
are sent by the client but not received by the server), | are sent by the client but not received by the server), | |||
it is possible for the grace period to expire before the client | it is possible for the grace period to expire before the client | |||
finds out that the server restart has occurred. | finds out that the server restart has occurred. | |||
</t> | </t> | |||
<t> | <t> | |||
Some additional time in | Some additional time in | |||
order to allow a client to | order to allow a client to | |||
establish a new client ID and session and to effect lock | establish a new client ID and session and to effect lock | |||
reclaims may be added to the lease time. Note that | reclaims may be added to the lease time. Note that | |||
analogous rules apply to | analogous rules apply to | |||
file system-specific grace periods discussed in | file system-specific grace periods discussed in | |||
<xref target="SEC11-EFF-lock"/>. | <xref target="SEC11-EFF-lock" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
If the server can reliably determine that granting a non-reclaim | If the server can reliably determine that granting a non-reclaim | |||
request will not conflict with reclamation of locks by other | request will not conflict with reclamation of locks by other | |||
clients, the NFS4ERR_GRACE error does not have to be returned | clients, the NFS4ERR_GRACE error does not have to be returned | |||
even within the grace period, although NFS4ERR_GRACE must always | even within the grace period, although NFS4ERR_GRACE must always | |||
be returned to clients attempting a non-reclaim lock request | be returned to clients attempting a non-reclaim lock request | |||
before doing their own global RECLAIM_COMPLETE. | before doing their own global RECLAIM_COMPLETE. | |||
For the server to be able | For the server to be able | |||
to service READ and WRITE operations during the grace period, it must | to service READ and WRITE operations during the grace period, it must | |||
again be able to guarantee that no possible conflict could arise | again be able to guarantee that no possible conflict could arise | |||
between a potential reclaim locking request and the READ or WRITE | between a potential reclaim locking request and the READ or WRITE | |||
operation. If the server is unable to offer that guarantee, the | operation. If the server is unable to offer that guarantee, the | |||
NFS4ERR_GRACE error must be returned to the client. | NFS4ERR_GRACE error must be returned to the client. | |||
</t> | </t> | |||
<t> | <t> | |||
For a server to provide simple, valid handling during the grace | For a server to provide simple, valid handling during the grace | |||
period, the easiest method is to simply reject all non-reclaim locking | period, the easiest method is to simply reject all non-reclaim locking | |||
requests and READ and WRITE operations by returning the NFS4ERR_GRACE | requests and READ and WRITE operations by returning the NFS4ERR_GRACE | |||
error. However, a server may keep information about granted locks in | error. However, a server may keep information about granted locks in | |||
stable storage. With this information, the server could determine if | stable storage. With this information, the server could determine if | |||
a locking, READ or WRITE operation can be safely processed. | a locking, READ or WRITE operation can be safely processed. | |||
</t> | </t> | |||
<t> | <t> | |||
For example, if the server maintained on stable storage summary | For example, if the server maintained on stable storage summary | |||
information on whether mandatory locks exist, either mandatory | information on whether mandatory locks exist, either mandatory | |||
byte-range locks, or share reservations specifying deny modes, | byte-range locks, or share reservations specifying deny modes, | |||
many requests could be allowed during the grace period. If it | many requests could be allowed during the grace period. If it | |||
is known that no such share reservations exist, OPEN request that | is known that no such share reservations exist, OPEN request that | |||
do not specify deny modes may be safely granted. If, in addition, | do not specify deny modes may be safely granted. If, in addition, | |||
it is known that no mandatory byte-range locks exist, either | it is known that no mandatory byte-range locks exist, either | |||
through information stored on stable storage or simply because | through information stored on stable storage or simply because | |||
the server does not support such locks, READ and WRITE operations | the server does not support such locks, READ and WRITE operations | |||
may be safely processed during the grace period. | may be safely processed during the grace period. | |||
Another important case is where it is known that no mandatory | Another important case is where it is known that no mandatory | |||
byte-range locks exist, either because the server does not | byte-range locks exist, either because the server does not | |||
provide support for them or because their absence is known | provide support for them or because their absence is known | |||
from persistently recorded data. In this case, READ and | from persistently recorded data. In this case, READ and | |||
WRITE operations specifying stateids derived from reclaim-type | WRITE operations specifying stateids derived from reclaim-type | |||
operations may be validly processed during the grace period | operations may be validly processed during the grace period | |||
because of the fact that the valid reclaim ensures that no lock | because of the fact that the valid reclaim ensures that no lock | |||
subsequently granted can prevent the I/O. | subsequently granted can prevent the I/O. | |||
</t> | </t> | |||
<t> | <t> | |||
To reiterate, for a server that allows non-reclaim lock and I/O | To reiterate, for a server that allows non-reclaim lock and I/O | |||
requests to be processed during the grace period, it MUST determine | requests to be processed during the grace period, it <bcp14>MUST</bcp14> determine | |||
that no lock subsequently reclaimed will be rejected and that no lock | that no lock subsequently reclaimed will be rejected and that no lock | |||
subsequently reclaimed would have prevented any I/O operation | subsequently reclaimed would have prevented any I/O operation | |||
processed during the grace period. | processed during the grace period. | |||
</t> | </t> | |||
<t> | <t> | |||
Clients should be prepared for the return of NFS4ERR_GRACE errors for | Clients should be prepared for the return of NFS4ERR_GRACE errors for | |||
non-reclaim lock and I/O requests. In this case, the client should | non-reclaim lock and I/O requests. In this case, the client should | |||
employ a retry mechanism for the request. A delay (on the order of | employ a retry mechanism for the request. A delay (on the order of | |||
several seconds) between retries should be used to avoid overwhelming | several seconds) between retries should be used to avoid overwhelming | |||
the server. Further discussion of the general issue is included in | the server. Further discussion of the general issue is included in | |||
<xref target="Floyd" />. The client must account for the server that | <xref target="Floyd" format="default"/>. The client must account for th e server that | |||
can perform I/O and non-reclaim locking requests within the grace period | can perform I/O and non-reclaim locking requests within the grace period | |||
as well as those that cannot do so. | as well as those that cannot do so. | |||
</t> | </t> | |||
<t> | <t> | |||
A reclaim-type locking request outside the server's grace period | A reclaim-type locking request outside the server's grace period | |||
can only succeed if the server can guarantee that no conflicting | can only succeed if the server can guarantee that no conflicting | |||
lock or I/O request has been granted since restart. | lock or I/O request has been granted since restart. | |||
</t> | </t> | |||
<t> | <t> | |||
A server may, upon restart, establish a new value for the lease | A server may, upon restart, establish a new value for the lease | |||
period. Therefore, clients should, once a new client ID is | period. Therefore, clients should, once a new client ID is | |||
established, refetch the lease_time attribute and use it as the basis | established, refetch the lease_time attribute and use it as the basis | |||
for lease renewal for the lease associated with that server. However, | for lease renewal for the lease associated with that server. However, | |||
the server must establish, for this restart event, a grace period at | the server must establish, for this restart event, a grace period at | |||
least as long as the lease period for the previous server | least as long as the lease period for the previous server | |||
instantiation. This allows the client state obtained during the | instantiation. This allows the client state obtained during the | |||
previous server instance to be reliably re-established. | previous server instance to be reliably re-established. | |||
</t> | </t> | |||
<t> | <t> | |||
The possibility exists that, because of server configuration | The possibility exists that, because of server configuration | |||
events, the client will be communicating with a server | events, the client will be communicating with a server | |||
different than the one on which the locks were obtained, as | different than the one on which the locks were obtained, as | |||
shown by the combination of eir_server_scope and | shown by the combination of eir_server_scope and | |||
eir_server_owner. This leads to the issue of if and when | eir_server_owner. This leads to the issue of if and when | |||
the client should attempt to reclaim locks previously obtained | the client should attempt to reclaim locks previously obtained | |||
on what is being reported as a different server. The rules | on what is being reported as a different server. The rules | |||
to resolve this question are as follows: | to resolve this question are as follows: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If the server scope is different, the client should not | If the server scope is different, the client should not | |||
attempt to reclaim locks. In this situation, no lock | attempt to reclaim locks. In this situation, no lock | |||
reclaim is possible. Any attempt to re-obtain the locks | reclaim is possible. Any attempt to re-obtain the locks | |||
with non-reclaim operations is problematic since there is | with non-reclaim operations is problematic since there is | |||
no guarantee that the existing filehandles will be recognized | no guarantee that the existing filehandles will be recognized | |||
by the new server, or that if recognized, they denote the | by the new server, or that if recognized, they denote the | |||
same objects. It is best to treat the locks as having been | same objects. It is best to treat the locks as having been | |||
revoked by the reconfiguration event. | revoked by the reconfiguration event. | |||
</t> | </li> | |||
<t> | <li> | |||
If the server scope is the same, the client should attempt | If the server scope is the same, the client should attempt | |||
to reclaim locks, even if the eir_server_owner value is | to reclaim locks, even if the eir_server_owner value is | |||
different. In this situation, it is the responsibility | different. In this situation, it is the responsibility | |||
of the server to return NFS4ERR_NO_GRACE if it cannot | of the server to return NFS4ERR_NO_GRACE if it cannot | |||
provide correct support for lock reclaim operations, | provide correct support for lock reclaim operations, | |||
including the prevention of edge conditions. | including the prevention of edge conditions. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The eir_server_owner field is not used in making this | The eir_server_owner field is not used in making this | |||
determination. Its function is to specify trunking | determination. Its function is to specify trunking | |||
possibilities for the client (see <xref target="Trunking" />) | possibilities for the client (see <xref target="Trunking" format="defaul t"/>) | |||
and not to control lock reclaim. | and not to control lock reclaim. | |||
</t> | </t> | |||
<section anchor="reclaim_security_considerations" | <section anchor="reclaim_security_considerations" numbered="true" to | |||
title="Security Considerations for State Reclaim" > | c="default"> | |||
<t> | <name>Security Considerations for State Reclaim</name> | |||
<t> | ||||
During the grace period, a client can reclaim state that it believes o r | During the grace period, a client can reclaim state that it believes o r | |||
asserts it had before the server restarted. Unless the server | asserts it had before the server restarted. Unless the server | |||
maintained a complete record of all the state the client had, | maintained a complete record of all the state the client had, | |||
the server has little choice but to trust the client. (Of course, | the server has little choice but to trust the client. (Of course, | |||
if the server maintained a complete record, then it would not | if the server maintained a complete record, then it would not | |||
have to force the client to reclaim state after server restart.) | have to force the client to reclaim state after server restart.) | |||
While the server has to trust the client to tell the truth, the | While the server has to trust the client to tell the truth, the | |||
negative consequences for security are limited to enabling | negative consequences for security are limited to enabling | |||
denial-of-service attacks in situations in which AUTH_SYS is | denial-of-service attacks in situations in which AUTH_SYS is | |||
supported. The | supported. The | |||
fundamental rule for the server when processing reclaim requests | fundamental rule for the server when processing reclaim requests | |||
is that it MUST NOT grant the reclaim if an equivalent non-reclaim | is that it <bcp14>MUST NOT</bcp14> grant the reclaim if an equivalent non-reclaim | |||
request would not be granted during steady state due to access | request would not be granted during steady state due to access | |||
control or access conflict issues. For example, an OPEN request | control or access conflict issues. For example, an OPEN request | |||
during a reclaim will be refused with NFS4ERR_ACCESS if the principal m aking | during a reclaim will be refused with NFS4ERR_ACCESS if the principal m aking | |||
the request does not have access to open the file according to the | the request does not have access to open the file according to the | |||
discretionary ACL (<xref target="attrdef_dacl"/>) on the file. | discretionary ACL (<xref target="attrdef_dacl" format="default"/>) on t | |||
he file. | ||||
</t> | ||||
<t> | </t> | |||
<t> | ||||
Nonetheless, it is possible that a client operating in error or | Nonetheless, it is possible that a client operating in error or | |||
maliciously could, during reclaim, prevent another client from | maliciously could, during reclaim, prevent another client from | |||
reclaiming access to state. For example, an attacker could | reclaiming access to state. For example, an attacker could | |||
send an OPEN reclaim operation with a deny mode that prevents | send an OPEN reclaim operation with a deny mode that prevents | |||
another client from reclaiming the OPEN state it had before the | another client from reclaiming the OPEN state it had before the | |||
server restarted. | server restarted. | |||
The attacker could perform the same denial of service during | The attacker could perform the same denial of service during | |||
steady state prior to server restart, as long as the | steady state prior to server restart, as long as the | |||
attacker had permissions. Given that the attack | attacker had permissions. Given that the attack | |||
vectors are equivalent, the grace period does not offer any | vectors are equivalent, the grace period does not offer any | |||
additional opportunity for denial of service, and any concerns | additional opportunity for denial of service, and any concerns | |||
about this attack vector, whether during grace or steady state, | about this attack vector, whether during grace or steady state, | |||
are addressed the same way: use RPCSEC_GSS for authentication | are addressed the same way: use RPCSEC_GSS for authentication | |||
and limit access to the file only to principals that the owner of | and limit access to the file only to principals that the owner of | |||
the file trusts. | the file trusts. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
Note that if prior to restart the server had client | Note that if prior to restart the server had client | |||
IDs with the EXCHGID4_FLAG_BIND_PRINC_STATEID (<xref | IDs with the EXCHGID4_FLAG_BIND_PRINC_STATEID (<xref target="OP_EXCH | |||
target="OP_EXCHANGE_ID"/>) capability set, then the server | ANGE_ID" format="default"/>) capability set, then the server | |||
SHOULD record in stable storage the client owner and the | <bcp14>SHOULD</bcp14> record in stable storage the client owner and t | |||
he | ||||
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> <!-- "Security Considerations for State Reclaim" --> | </section> | |||
</section> <!-- "State Reclaim" --> | </section> | |||
</section> <!-- "Server Failure and Recovery" --> | <section anchor="network_partitions_and_recovery" numbered="true" toc="defau | |||
<section anchor="network_partitions_and_recovery" | lt"> | |||
title="Network Partitions and Recovery"> | <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 | |||
granted but MUST be revoked as necessary so as to avoid interfering with | granted but <bcp14>MUST</bcp14> be revoked as necessary so as to avoid i nterfering with | |||
such conflicting requests. | such conflicting requests. | |||
</t> | </t> | |||
<t> | <t> | |||
If the server chooses to delay freeing of lock state until there | If the server chooses to delay freeing of lock state until there | |||
is a conflict, it may either free all of the client's locks once | is a conflict, it may either free all of the client's locks once | |||
there is a conflict or it may only revoke the minimum set of locks | there is a conflict or it may only revoke the minimum set of locks | |||
necessary to allow conflicting requests. When it adopts the | necessary to allow conflicting requests. When it adopts the | |||
finer-grained approach, it must revoke all locks associated with a | finer-grained approach, it must revoke all locks associated with a | |||
given stateid, even if the conflict is with only a subset of locks. | given stateid, even if the conflict is with only a subset of locks. | |||
</t> | </t> | |||
<t> | <t> | |||
When the server chooses to free all of a client's lock state, either | When the server chooses to free all of a client's lock state, either | |||
immediately upon lease expiration or as a result of the first | immediately upon lease expiration or as a result of the first | |||
attempt to obtain a conflicting a lock, the server may report the | attempt to obtain a conflicting a lock, the server may report the | |||
loss of lock state in a number of ways. | loss of lock state in a number of ways. | |||
</t> | </t> | |||
<t> | <t> | |||
The server may choose to invalidate the session and the associated | The server may choose to invalidate the session and the associated | |||
client ID. In this case, once the client can communicate | client ID. In this case, once the client can communicate | |||
with the server, it will receive an NFS4ERR_BADSESSION error. Upon | with the server, it will receive an NFS4ERR_BADSESSION error. Upon | |||
attempting to create a new session, it would get an | attempting to create a new session, it would get an | |||
NFS4ERR_STALE_CLIENTID. Upon creating the new client ID and new | NFS4ERR_STALE_CLIENTID. Upon creating the new client ID and new | |||
session, the client will attempt to reclaim locks. Normally, the | session, the client will attempt to reclaim locks. Normally, the | |||
server will not allow the client to reclaim locks, because the | server will not allow the client to reclaim locks, because the | |||
server will not be in its recovery grace period. | server will not be in its recovery grace period. | |||
</t> | </t> | |||
<t> | <t> | |||
Another possibility is for the server to maintain the session and | Another possibility is for the server to maintain the session and | |||
client ID but for all stateids held by the | client ID but for all stateids held by the | |||
client to become invalid or stale. Once the client can reach | client to become invalid or stale. Once the client can reach | |||
the server after such a network partition, the status returned by | the server after such a network partition, the status returned by | |||
the SEQUENCE operation will indicate a loss of locking state; i.e., | the SEQUENCE operation will indicate a loss of locking state; i.e., | |||
the flag SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED will be set in | the flag SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED will be set in | |||
sr_status_flags. In | sr_status_flags. In | |||
addition, all I/O submitted by the | addition, all I/O submitted by the | |||
client with the now invalid stateids will fail with the server | client with the now invalid stateids will fail with the server | |||
returning the error NFS4ERR_EXPIRED. Once the client learns of | returning the error NFS4ERR_EXPIRED. Once the client learns of | |||
the loss of locking state, it | the loss of locking state, it | |||
will suitably notify the applications that held the invalidated | will suitably notify the applications that held the invalidated | |||
locks. The client should then take action to free invalidated | locks. The client should then take action to free invalidated | |||
stateids, either by establishing a new client ID using a new | stateids, either by establishing a new client ID using a new | |||
verifier or by doing a FREE_STATEID operation to release each | verifier or by doing a FREE_STATEID operation to release each | |||
of the invalidated stateids. | of the invalidated stateids. | |||
</t> | </t> | |||
<t> | <t> | |||
When the server adopts a finer-grained approach to revocation | When the server adopts a finer-grained approach to revocation | |||
of locks when a client's lease has expired, only a subset of stateids | of locks when a client's lease has expired, only a subset of stateids | |||
will normally become invalid during a network partition. | will normally become invalid during a network partition. | |||
When the client can communicate with the server after such a | When the client can communicate with the server after such a | |||
network partition heals, the status returned by the SEQUENCE | network partition heals, the status returned by the SEQUENCE | |||
operation will indicate a partial loss of locking state | operation will indicate a partial loss of locking state | |||
(SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED). | (SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED). | |||
In addition, operations, including I/O submitted by the | In addition, operations, including I/O submitted by the | |||
client, with the now invalid stateids will fail with the server | client, with the now invalid stateids will fail with the server | |||
returning the error NFS4ERR_EXPIRED. Once the client learns of | returning the error NFS4ERR_EXPIRED. Once the client learns of | |||
the loss of locking state, it will use the TEST_STATEID operation | the loss of locking state, it will use the TEST_STATEID operation | |||
on all of its stateids to | on all of its stateids to | |||
determine which locks have been lost and then | determine which locks have been lost and then | |||
suitably notify the applications that held the invalidated | suitably notify the applications that held the invalidated | |||
locks. The client can then release the invalidated locking | locks. The client can then release the invalidated locking | |||
state and acknowledge the revocation of the associated locks | state and acknowledge the revocation of the associated locks | |||
by doing a FREE_STATEID operation on each of the invalidated | by doing a FREE_STATEID operation on each of the invalidated | |||
stateids. | stateids. | |||
</t> | </t> | |||
<t> | <t> | |||
When a network partition is combined with a server restart, there are | When a network partition is combined with a server restart, there are | |||
edge conditions that place requirements on the server in order to | edge conditions that place requirements on the server in order to | |||
avoid silent data corruption following the server restart. Two of these | avoid silent data corruption following the server restart. Two of these | |||
edge conditions are known, and are discussed below. | edge conditions are known, and are discussed below. | |||
</t> | </t> | |||
<t> | <t> | |||
The first edge condition arises as a result of the scenarios such as | The first edge condition arises as a result of the scenarios such as | |||
the following: | the following: | |||
<list style='numbers'> | ||||
<t> | ||||
Client A acquires a lock. | ||||
</t> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
Client A acquires a lock. | ||||
</li> | ||||
<li> | ||||
Client A and server experience mutual network partition, such that | Client A and server experience mutual network partition, such that | |||
client A is unable to renew its lease. | client A is unable to renew its lease. | |||
</t> | </li> | |||
<t> | <li> | |||
Client A's lease expires, and the server releases the lock. | Client A's lease expires, and the server releases the lock. | |||
</t> | </li> | |||
<t> | <li> | |||
Client B acquires a lock that would have conflicted | Client B acquires a lock that would have conflicted | |||
with that of client A. | with that of client A. | |||
</t> | </li> | |||
<t> | <li> | |||
Client B releases its lock. | Client B releases its lock. | |||
</t> | </li> | |||
<t> | <li> | |||
Server restarts. | Server restarts. | |||
</t> | </li> | |||
<t> | <li> | |||
Network partition between client A and server heals. | Network partition between client A and server heals. | |||
</t> | </li> | |||
<t> | <li> | |||
Client A connects to a new server instance and finds out about | Client A connects to a new server instance and finds out about | |||
server restart. | server restart. | |||
</t> | </li> | |||
<t> | <li> | |||
Client A reclaims its lock within the server's grace period. | Client A reclaims its lock within the server's grace period. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | <t> | |||
<t> | ||||
Thus, at the final step, the server has erroneously granted client A's | Thus, at the final step, the server has erroneously granted client A's | |||
lock reclaim. If client B modified the object the lock was protecting, | lock reclaim. If client B modified the object the lock was protecting, | |||
client A will experience object corruption. | client A will experience object corruption. | |||
</t> | ||||
<t> | ||||
The second known edge condition arises in situations such as the followi | ||||
ng: | ||||
<list style="numbers"> | ||||
<t> | ||||
Client A acquires one or more locks. | ||||
</t> | </t> | |||
<t> | <t> | |||
Server restarts. | The second known edge condition arises in situations such as the followi ng: | |||
</t> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
Client A acquires one or more locks. | ||||
</li> | ||||
<li> | ||||
Server restarts. | ||||
</li> | ||||
<li> | ||||
Client A and server experience mutual network | Client A and server experience mutual network | |||
partition, such that client A is unable to reclaim | partition, such that client A is unable to reclaim | |||
all of its locks within the grace period. | all of its locks within the grace period. | |||
</t> | </li> | |||
<t> | <li> | |||
Server's reclaim grace period ends. Client A has either | Server's reclaim grace period ends. Client A has either | |||
no locks or an incomplete set of locks known to the server. | no locks or an incomplete set of locks known to the server. | |||
</t> | </li> | |||
<t> | <li> | |||
Client B acquires a lock that would have conflicted | Client B acquires a lock that would have conflicted | |||
with a lock of client A that was not reclaimed. | with a lock of client A that was not reclaimed. | |||
</t> | </li> | |||
<t> | <li> | |||
Client B releases the lock. | Client B releases the lock. | |||
</t> | </li> | |||
<t> | <li> | |||
Server restarts a second time. | Server restarts a second time. | |||
</t> | </li> | |||
<t> | <li> | |||
Network partition between client A and server heals. | Network partition between client A and server heals. | |||
</t> | </li> | |||
<t> | <li> | |||
Client A connects to new server instance and finds out about | Client A connects to new server instance and finds out about | |||
server restart. | server restart. | |||
</t> | </li> | |||
<t> | <li> | |||
Client A reclaims its lock within the server's | Client A reclaims its lock within the server's | |||
grace period. | grace period. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | <t> | |||
<t> | ||||
As with the first edge condition, the final step of the scenario of | As with the first edge condition, the final step of the scenario of | |||
the second edge condition has the server erroneously granting client | the second edge condition has the server erroneously granting client | |||
A's lock reclaim. | A's lock reclaim. | |||
</t> | </t> | |||
<t> | <t> | |||
Solving the first and second edge conditions requires either that the se rver | Solving the first and second edge conditions requires either that the se rver | |||
always assumes after it restarts that some edge condition | always assumes after it restarts that some edge condition | |||
occurs, and thus returns NFS4ERR_NO_GRACE for all reclaim attempts, or t hat the server | occurs, and thus returns NFS4ERR_NO_GRACE for all reclaim attempts, or t hat the server | |||
record some information in stable storage. The amount | record some information in stable storage. The amount | |||
of information the | of information the | |||
server records in stable storage is in inverse proportion to how harsh | server records in stable storage is in inverse proportion to how harsh | |||
the server intends to be whenever edge conditions arise. | the server intends to be whenever edge conditions arise. | |||
The server | The server | |||
that is completely tolerant of all edge conditions will record in | that is completely tolerant of all edge conditions will record in | |||
stable storage every lock that is acquired, removing the lock record | stable storage every lock that is acquired, removing the lock record | |||
from stable storage only when the lock is released. | from stable storage only when the lock is released. | |||
For the two edge conditions discussed above, the harshest a | For the two edge conditions discussed above, the harshest a | |||
server can be, and still support a grace period for reclaims, requires | server can be, and still support a grace period for reclaims, requires | |||
that the server record in stable storage some minimal | that the server record in stable storage some minimal | |||
information. For example, a server implementation could, for each | information. For example, a server implementation could, for each | |||
client, save in stable storage a record containing: | client, save in stable storage a record containing: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
the co_ownerid field from the client_owner4 presented in the | the co_ownerid field from the client_owner4 presented in the | |||
EXCHANGE_ID operation. | EXCHANGE_ID operation. | |||
</t> | </li> | |||
<t> | <li> | |||
a boolean that indicates if the client's lease expired | a boolean that indicates if the client's lease expired | |||
or if there was administrative intervention (see | or if there was administrative intervention (see | |||
<xref target="server_revocation" />) to revoke | <xref target="server_revocation" format="default"/>) to revoke | |||
a byte-range lock, share reservation, or delegation and | a byte-range lock, share reservation, or delegation and | |||
there has been no acknowledgment, via FREE_STATEID, | there has been no acknowledgment, via FREE_STATEID, | |||
of such revocation. | of such revocation. | |||
</t> | </li> | |||
<t> | <li> | |||
a boolean that indicates whether the client may have locks | a boolean that indicates whether the client may have locks | |||
that it believes to be reclaimable in situations in which the | that it believes to be reclaimable in situations in which the | |||
grace period was terminated, making the server's view of | grace period was terminated, making the server's view of | |||
lock reclaimability suspect. The server will set this for | lock reclaimability suspect. The server will set this for | |||
any client record in stable storage where the client has | any client record in stable storage where the client has | |||
not done a suitable RECLAIM_COMPLETE (global or file | not done a suitable RECLAIM_COMPLETE (global or file | |||
system-specific depending on the target of the lock | system-specific depending on the target of the lock | |||
request) before it grants any new (i.e., not reclaimed) | request) before it grants any new (i.e., not reclaimed) | |||
lock to any client. | lock to any client. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Assuming the above record keeping, for the first edge condition, after | Assuming the above record keeping, for the first edge condition, after | |||
the server restarts, the record that client A's lease expired means | the server restarts, the record that client A's lease expired means | |||
that another client could have acquired a conflicting byte-range lock, | that another client could have acquired a conflicting byte-range lock, | |||
share reservation, or delegation. Hence, the server must reject a | share reservation, or delegation. Hence, the server must reject a | |||
reclaim from client A with the error NFS4ERR_NO_GRACE. | reclaim from client A with the error NFS4ERR_NO_GRACE. | |||
</t> | </t> | |||
<t> | <t> | |||
For the second edge condition, after the server restarts for a second | For the second edge condition, after the server restarts for a second | |||
time, the indication that the client had not completed its | time, the indication that the client had not completed its | |||
reclaims at the time at which the grace period ended | reclaims at the time at which the grace period ended | |||
means that the server must reject a reclaim from client A | means that the server must reject a reclaim from client A | |||
with the error NFS4ERR_NO_GRACE. | with the error NFS4ERR_NO_GRACE. | |||
</t> | </t> | |||
<t> | <t> | |||
When either edge condition occurs, the client's attempt to reclaim | When either edge condition occurs, the client's attempt to reclaim | |||
locks will result in the error NFS4ERR_NO_GRACE. When this is | locks will result in the error NFS4ERR_NO_GRACE. When this is | |||
received, or after the client restarts with no lock state, the | received, or after the client restarts with no lock state, the | |||
client will send a global RECLAIM_COMPLETE. When | client will send a global RECLAIM_COMPLETE. When | |||
the RECLAIM_COMPLETE is received, the server and client are | the RECLAIM_COMPLETE is received, the server and client are | |||
again in agreement regarding reclaimable locks and both booleans in pers istent | again in agreement regarding reclaimable locks and both booleans in pers istent | |||
storage can be reset, to be set again only when there is a subsequent | storage can be reset, to be set again only when there is a subsequent | |||
event that causes lock reclaim operations to be questionable. | event that causes lock reclaim operations to be questionable. | |||
</t> | </t> | |||
<t> | <t> | |||
Regardless of the level and approach to record keeping, the server | Regardless of the level and approach to record keeping, the server | |||
MUST implement one of the following strategies (which apply to | <bcp14>MUST</bcp14> implement one of the following strategies (which app ly to | |||
reclaims of share reservations, byte-range locks, and delegations): | reclaims of share reservations, byte-range locks, and delegations): | |||
<list style="numbers"> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
Reject all reclaims with NFS4ERR_NO_GRACE. This | Reject all reclaims with NFS4ERR_NO_GRACE. This | |||
is extremely unforgiving, but necessary if the server does not | is extremely unforgiving, but necessary if the server does not | |||
record lock state in stable storage. | record lock state in stable storage. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
Record sufficient state in stable storage such that | Record sufficient state in stable storage such that | |||
all known edge conditions involving server restart, | all known edge conditions involving server restart, | |||
including the two noted in this section, are | including the two noted in this section, are | |||
detected. It is acceptable to erroneously recognize an edge conditi on | detected. It is acceptable to erroneously recognize an edge conditi on | |||
and not allow a reclaim, when, with sufficient knowledge, it | and not allow a reclaim, when, with sufficient knowledge, it | |||
would be allowed. The error the server would return in this | would be allowed. The error the server would return in this | |||
case is NFS4ERR_NO_GRACE. Note that it is not known if there are ot her | case is NFS4ERR_NO_GRACE. Note that it is not known if there are ot her | |||
edge conditions. | edge conditions. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
In the event that, after a server restart, the server | In the event that, after a server restart, the server | |||
determines there is unrecoverable damage or | determines there is unrecoverable damage or | |||
corruption to the information in stable storage, then for | corruption to the information in stable storage, then for | |||
all clients and/or locks that may be affected, the server MUST | all clients and/or locks that may be affected, the server <bcp14>MUS T</bcp14> | |||
return NFS4ERR_NO_GRACE. | return NFS4ERR_NO_GRACE. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ol> | |||
<t> | <t> | |||
A mandate for the client's handling of the NFS4ERR_NO_GRACE error is | A mandate for the client's handling of the NFS4ERR_NO_GRACE error is | |||
outside the scope of this specification, since the strategies for such | outside the scope of this specification, since the strategies for such | |||
handling are very dependent on the client's operating environment. | handling are very dependent on the client's operating environment. | |||
However, one potential approach is described below. | However, one potential approach is described below. | |||
</t> | </t> | |||
<t> | <t> | |||
When the client receives NFS4ERR_NO_GRACE, it could examine the change | When the client receives NFS4ERR_NO_GRACE, it could examine the change | |||
attribute of the objects for which the client is trying to reclaim stat e, | attribute of the objects for which the client is trying to reclaim stat e, | |||
and use that to determine whether to re-establish the state via normal | and use that to determine whether to re-establish the state via normal | |||
OPEN or LOCK operations. This is acceptable provided that the client's | OPEN or LOCK operations. This is acceptable provided that the client's | |||
operating environment allows it. In other words, the client | operating environment allows it. In other words, the client | |||
implementor is advised to document for his users the behavior. The | implementor is advised to document for his users the behavior. The | |||
client could also inform the application that its byte-range lock or sha re | client could also inform the application that its byte-range lock or sha re | |||
reservations (whether or not they were delegated) have been lost, such | reservations (whether or not they were delegated) have been lost, such | |||
as via a UNIX signal, a Graphical User Interface (GUI) pop-up window, et c. | as via a UNIX signal, a Graphical User Interface (GUI) pop-up window, et c. | |||
See <xref target="data_caching_revocation" /> | 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" />. | <xref target="server_revocation" format="default"/>. | |||
</t> | </t> | |||
</section> <!-- "Network Partitions and Recovery" --> | </section> | |||
</section> <!-- "Crash Recovery" --> | </section> | |||
<section anchor="server_revocation" title="Server Revocation of Locks" > | <section anchor="server_revocation" numbered="true" toc="default"> | |||
<t> | <name>Server Revocation of Locks</name> | |||
<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> | |||
<t> | <t> | |||
The first occasion of lock revocation is upon server | The first occasion of lock revocation is upon server | |||
restart. Note that this includes situations | restart. Note that this includes situations | |||
in which sessions are persistent and locking state is | in which sessions are persistent and locking state is | |||
lost. In this class of instances, the client will | lost. In this class of instances, the client will | |||
receive an error (NFS4ERR_STALE_CLIENTID) on an | receive an error (NFS4ERR_STALE_CLIENTID) on an | |||
operation that takes client ID, usually as part of | operation that takes client ID, usually as part of | |||
recovery in response to a problem with the current | recovery in response to a problem with the current | |||
session), and the client will proceed | session), and the client will proceed | |||
with normal crash recovery as described in the <xref | with normal crash recovery as described in the <xref target="reclaim_locks | |||
target="reclaim_locks" />. | " format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
The second occasion of lock revocation is the inability to renew the lease | The second occasion of lock revocation is the inability to renew the lease | |||
before expiration, as discussed in | before expiration, as discussed in | |||
<xref target="network_partitions_and_recovery" />. While this is | <xref target="network_partitions_and_recovery" format="default"/>. While t his is | |||
considered a rare or unusual event, | considered a rare or unusual event, | |||
the client must be prepared to recover. The server is responsible | the client must be prepared to recover. The server is responsible | |||
for determining the precise consequences of the lease expiration, | for determining the precise consequences of the lease expiration, | |||
informing the client of the scope of the lock revocation decided | informing the client of the scope of the lock revocation decided | |||
upon. The client then uses the status information provided | upon. The client then uses the status information provided | |||
by the server in the SEQUENCE results (field sr_status_flags, | by the server in the SEQUENCE results (field sr_status_flags, | |||
see <xref target="OP_SEQUENCE_DESCRIPTION" />) | see <xref target="OP_SEQUENCE_DESCRIPTION" format="default"/>) | |||
to synchronize its locking state with that of the | to synchronize its locking state with that of the | |||
server, in order to recover. | server, in order to recover. | |||
</t> | </t> | |||
<t> | <t> | |||
The third occasion of lock revocation can occur as a result of | The third occasion of lock revocation can occur as a result of | |||
revocation of locks within the lease period, either because of | revocation of locks within the lease period, either because of | |||
administrative intervention or because a recallable lock (a | administrative intervention or because a recallable lock (a | |||
delegation or layout) was not returned within the lease period | delegation or layout) was not returned within the lease period | |||
after having been recalled. While these are | after having been recalled. While these are | |||
considered rare events, they are possible, and the client must be | considered rare events, they are possible, and the client must be | |||
prepared to deal with them. When either of these events occurs, | prepared to deal with them. When either of these events occurs, | |||
the client finds out about the situation through the status returned | the client finds out about the situation through the status returned | |||
by the SEQUENCE operation. Any use of stateids associated with | by the SEQUENCE operation. Any use of stateids associated with | |||
locks revoked during the lease period will receive the error | locks revoked during the lease period will receive the error | |||
NFS4ERR_ADMIN_REVOKED or NFS4ERR_DELEG_REVOKED, as appropriate. | NFS4ERR_ADMIN_REVOKED or NFS4ERR_DELEG_REVOKED, as appropriate. | |||
</t> | </t> | |||
<t> | <t> | |||
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> <!-- "Server Revocation of Locks" --> | </section> | |||
<section title="Short and Long Leases" > | <section numbered="true" toc="default"> | |||
<t> | <name>Short and Long Leases</name> | |||
<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 | |||
tradeoffs 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 ext ra requests | servers trying to handle very large numbers of clients. The number of ext ra requests | |||
to effect lock renewal drops in inverse | to effect lock renewal drops in inverse | |||
proportion to the lease time. The disadvantages of a long lease | proportion to the lease time. The disadvantages of a long lease | |||
include the possibility of slower recovery after certain failures. | include the possibility of slower recovery after certain failures. | |||
After server failure, a longer grace period may be required when | After server failure, a longer grace period may be required when | |||
some clients do not promptly reclaim their locks and do a | some clients do not promptly reclaim their locks and do a | |||
global RECLAIM_COMPLETE. In the event of client failure, | global RECLAIM_COMPLETE. In the event of client failure, | |||
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> <!-- "Short and Long Leases" --> | </section> | |||
<section anchor="lease_propagation_delay" title="Clocks, Propagation Delay, an | <section anchor="lease_propagation_delay" numbered="true" toc="default"> | |||
d Calculating Lease Expiration" > | <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. | |||
</t> | </t> | |||
<t> | <t> | |||
To take propagation delay into account, the client should | To take propagation delay into account, the client should | |||
subtract it from lease times (e.g., if the client estimates the | subtract it from lease times (e.g., if the client estimates the | |||
one-way propagation delay as 200 milliseconds, then it can | one-way propagation delay as 200 milliseconds, then it can | |||
assume that the lease is already 200 milliseconds old when it | assume that the lease is already 200 milliseconds old when it | |||
gets it). In addition, it will take another 200 milliseconds to | gets it). In addition, it will take another 200 milliseconds to | |||
get a response back to the server. So the client must send a | get a response back to the server. So the client must send a | |||
lease renewal or write data back to the server at least 400 | lease renewal or write data back to the server at least 400 | |||
milliseconds before the lease would expire. If the propagation delay | milliseconds before the lease would expire. If the propagation delay | |||
varies over the life of the lease (e.g., the client is on a mobile | varies over the life of the lease (e.g., the client is on a mobile | |||
host), the client will need to continuously subtract the increase | host), the client will need to continuously subtract the increase | |||
in propagation delay from the lease times. | in propagation delay from the lease times. | |||
</t> | </t> | |||
<t> | <t> | |||
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> <!-- "Clocks, Propagation Delay, and Calculating Lease Expiration" | </section> | |||
--> | <section anchor="vestigial_locking" numbered="true" toc="default"> | |||
<section title="Obsolete Locking Infrastructure from NFSv4.0" anchor="vestigia | <name>Obsolete Locking Infrastructure from NFSv4.0</name> | |||
l_locking" > | <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> | |||
<t> | ||||
The following NFSv4.0 operations MUST NOT be implemented in NFSv4.1. | ||||
The server MUST return NFS4ERR_NOTSUPP if these operations are | ||||
found in an NFSv4.1 COMPOUND. | ||||
<list style='symbols'> | ||||
<t> | <t> | |||
The following NFSv4.0 operations <bcp14>MUST NOT</bcp14> be implemented in | ||||
NFSv4.1. | ||||
The server <bcp14>MUST</bcp14> return NFS4ERR_NOTSUPP if these operations | ||||
are | ||||
found in an NFSv4.1 COMPOUND. | ||||
</t> | ||||
<ul spacing="normal"> | ||||
<li> | ||||
SETCLIENTID since its function has been replaced by | SETCLIENTID since its function has been replaced by | |||
EXCHANGE_ID. | EXCHANGE_ID. | |||
</t> | </li> | |||
<t> | <li> | |||
SETCLIENTID_CONFIRM since client ID confirmation now | SETCLIENTID_CONFIRM since client ID confirmation now | |||
happens by means of CREATE_SESSION. | happens by means of CREATE_SESSION. | |||
</t> | </li> | |||
<t> | <li> | |||
OPEN_CONFIRM because state-owner-based seqids | OPEN_CONFIRM because state-owner-based seqids | |||
have been replaced by the sequence ID in the | have been replaced by the sequence ID in the | |||
SEQUENCE operation. | SEQUENCE operation. | |||
</t> | </li> | |||
<t> | <li> | |||
RELEASE_LOCKOWNER because lock-owners with no associated | RELEASE_LOCKOWNER because lock-owners with no associated | |||
locks do not have any sequence-related state and so can | locks do not have any sequence-related state and so can | |||
be deleted by the server at will. | be deleted by the server at will. | |||
</t> | </li> | |||
<t> | <li> | |||
RENEW because every SEQUENCE operation for a session causes | RENEW because every SEQUENCE operation for a session causes | |||
lease renewal, making a separate operation superfluous. | lease renewal, making a separate operation superfluous. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Also, there are a number of fields, present in existing operations, | Also, there are a number of fields, present in existing operations, | |||
related to locking that have no use in minor version 1. They | related to locking that have no use in minor version 1. They | |||
were used in minor version 0 to perform functions now provided | were used in minor version 0 to perform functions now provided | |||
in a different | in a different | |||
fashion. | fashion. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Sequence ids used to sequence requests for a given state-owner | Sequence ids used to sequence requests for a given state-owner | |||
and to provide retry protection, now provided | and to provide retry protection, now provided | |||
via sessions. | via sessions. | |||
</t> | </li> | |||
<t> | <li> | |||
Client IDs used to identify the client associated with a given | Client IDs used to identify the client associated with a given | |||
request. Client identification is now available using the client ID | request. Client identification is now available using the client ID | |||
associated with the current session, without needing an explicit | associated with the current session, without needing an explicit | |||
client ID field. | client ID field. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <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> <!-- "Vestigial Locking Infrastructure From V4.0" --> | </section> | |||
</section> <!-- "State Management" --> | </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 title="File Locking and Share Reservations" anchor="file_locking"> | <section anchor="file_locking" numbered="true" toc="default"> | |||
<t> | <name>File Locking and Share Reservations</name> | |||
<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, | |||
ACCESS) need to be replaced. The NFSv4.1 protocol defines | ACCESS) need to be replaced. The NFSv4.1 protocol defines | |||
an OPEN operation that is capable of atomically looking up, creating, | an OPEN operation that is capable of atomically looking up, creating, | |||
and locking a file on the server. | and locking a file on the server. | |||
</t> | </t> | |||
<section title="Opens and Byte-Range Locks" > | <section numbered="true" toc="default"> | |||
<t> | <name>Opens and Byte-Range Locks</name> | |||
<t> | ||||
It is assumed that manipulating a byte-range lock is rare when | It is assumed that manipulating a byte-range lock is rare when | |||
compared to READ | compared to READ | |||
and WRITE operations. It is also assumed that server restarts and network | and WRITE operations. It is also assumed that server restarts and network | |||
partitions are relatively rare. Therefore, it is important that the | partitions are relatively rare. Therefore, it is important that the | |||
READ and WRITE operations have a lightweight mechanism to indicate if | READ and WRITE operations have a lightweight mechanism to indicate if | |||
they possess a held lock. A LOCK operation contains the | they possess a held lock. A LOCK operation contains the | |||
heavyweight information required to establish a byte-range lock and unique ly | heavyweight information required to establish a byte-range lock and unique ly | |||
define the owner of the lock. | define the owner of the lock. | |||
</t> | </t> | |||
<section anchor="state-owner" title="State-Owner Definition" > | <section anchor="state-owner" numbered="true" toc="default"> | |||
<t> | <name>State-Owner Definition</name> | |||
<t> | ||||
When opening a file or requesting a byte-range lock, the | When opening a file or requesting a byte-range lock, the | |||
client must specify an identifier that represents the owner of | client must specify an identifier that represents the owner of | |||
the requested lock. This identifier is in the form of a | the requested lock. This identifier is in the form of a | |||
state-owner, represented in the protocol by a state_owner4, a | state-owner, represented in the protocol by a state_owner4, a | |||
variable-length opaque array that, when concatenated with the | variable-length opaque array that, when concatenated with the | |||
current client ID, uniquely defines the owner of a lock managed | current client ID, uniquely defines the owner of a lock managed | |||
by the client. This may be a thread ID, process ID, or other | by the client. This may be a thread ID, process ID, or other | |||
unique value. | unique value. | |||
</t> | </t> | |||
<t> | <t> | |||
Owners of opens and owners of byte-range locks are separate | Owners of opens and owners of byte-range locks are separate | |||
entities and remain separate even if the same opaque arrays | entities and remain separate even if the same opaque arrays | |||
are used to designate owners of each. The protocol distinguishes | are used to designate owners of each. The protocol distinguishes | |||
between open-owners (represented by open_owner4 structures) | between open-owners (represented by open_owner4 structures) | |||
and lock-owners (represented by lock_owner4 structures). | and lock-owners (represented by lock_owner4 structures). | |||
</t> | </t> | |||
<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> <!-- "State-owner Definition" --> | </section> | |||
<section title="Use of the Stateid and Locking" > | <section numbered="true" toc="default"> | |||
<t> | <name>Use of the Stateid and Locking</name> | |||
<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 t o the | between the old and new sizes (i.e., the byte-range truncated or added t o 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 mu st | mentioned in the text. The stateid passed to one of these operations mu st | |||
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 | |||
delegation, or it may be a special stateid representing anonymous | delegation, or it may be a special stateid representing anonymous | |||
access or the special bypass stateid. | access or the special bypass stateid. | |||
</t> | </t> | |||
<t> | <t> | |||
If the state-owner performs a READ or WRITE operation in a situation in which | If the state-owner performs a READ or WRITE operation in a situation in which | |||
it has established a byte-range lock or share reservation | it has established a byte-range lock or share reservation | |||
on the server (any OPEN constitutes a share reservation), the | on the server (any OPEN constitutes a share reservation), the | |||
stateid (previously returned by the server) must be used to | stateid (previously returned by the server) must be used to | |||
indicate what locks, including both byte-range | indicate what locks, including both byte-range | |||
locks and share reservations, are held by the state-owner. If no state | locks and share reservations, are held by the state-owner. If no state | |||
is established by the client, either a byte-range lock or a share reserv ation, | is established by the client, either a byte-range lock or a share reserv ation, | |||
a special stateid for anonymous state (zero as the value for "other" and "seqid") | a special stateid for anonymous state (zero as the value for "other" and "seqid") | |||
is used. (See <xref target='special_stateid' /> for a description of | is used. (See <xref target="special_stateid" format="default"/> for a d escription of | |||
'special' stateids in general.) | 'special' stateids in general.) | |||
Regardless of whether a stateid for anonymous state | Regardless of whether a stateid for anonymous state | |||
or a stateid returned by the server is used, if there is a | or a stateid returned by the server is used, if there is a | |||
conflicting share reservation or mandatory byte-range lock held on the | conflicting share reservation or mandatory byte-range lock held on the | |||
file, the server MUST refuse to service the READ or WRITE operation. | file, the server <bcp14>MUST</bcp14> refuse to service the READ or WRITE | |||
</t> | operation. | |||
<t> | </t> | |||
<t> | ||||
Share reservations are established by OPEN operations and by their | Share reservations are established by OPEN operations and by their | |||
nature are mandatory in that when the OPEN denies READ or WRITE | nature are mandatory in that when the OPEN denies READ or WRITE | |||
operations, that denial results in such operations being rejected with | operations, that denial results in such operations being rejected with | |||
error NFS4ERR_LOCKED. Byte-range locks may be implemented by the server | error NFS4ERR_LOCKED. Byte-range locks may be implemented by the server | |||
as either mandatory or advisory, or the choice of mandatory or | as either mandatory or advisory, or the choice of mandatory or | |||
advisory behavior may be determined by the server on the basis of the | advisory behavior may be determined by the server on the basis of the | |||
file being accessed (for example, some UNIX-based servers support a | file being accessed (for example, some UNIX-based servers support a | |||
"mandatory lock bit" on the mode attribute such that if set, byte-range | "mandatory lock bit" on the mode attribute such that if set, byte-range | |||
locks are required on the file before I/O is possible). When byte-range | locks are required on the file before I/O is possible). When byte-range | |||
locks are advisory, they only prevent the granting of conflicting lock | locks are advisory, they only prevent the granting of conflicting lock | |||
requests and have no effect on READs or WRITEs. Mandatory byte-range | requests and have no effect on READs or WRITEs. Mandatory byte-range | |||
locks, however, prevent conflicting I/O operations. When they are | locks, however, prevent conflicting I/O operations. When they are | |||
attempted, they are rejected with NFS4ERR_LOCKED. When the client | attempted, they are rejected with NFS4ERR_LOCKED. When the client | |||
gets NFS4ERR_LOCKED on a file for which it knows it has the proper share | gets NFS4ERR_LOCKED on a file for which it knows it has the proper share | |||
reservation, it will need to send a LOCK operation on the byte-range of | reservation, it will need to send a LOCK operation on the byte-range of | |||
the file that includes the byte-range the I/O was to be performed on, wi th | the file that includes the byte-range the I/O was to be performed on, wi th | |||
an appropriate locktype field of the LOCK operation's arguments (i.e., R EAD*_LT for a READ operation, WRITE*_LT | an appropriate locktype field of the LOCK operation's arguments (i.e., R EAD*_LT for a READ operation, WRITE*_LT | |||
for a WRITE operation). | for a WRITE operation). | |||
</t> | </t> | |||
<t> | <t> | |||
Note that for UNIX environments that support mandatory byte-range lockin g, | Note that for UNIX environments that support mandatory byte-range lockin g, | |||
the distinction between advisory and mandatory locking is subtle. In | the distinction between advisory and mandatory locking is subtle. In | |||
fact, advisory and mandatory byte-range locks are exactly the same as | fact, advisory and mandatory byte-range locks are exactly the same as | |||
far as the APIs and requirements on implementation. If the mandatory | far as the APIs and requirements on implementation. If the mandatory | |||
lock attribute is set on the file, the server checks to see if the | lock attribute is set on the file, the server checks to see if the | |||
lock-owner has an appropriate shared (READ_LT) or exclusive (WRITE_LT) b yte-range | lock-owner has an appropriate shared (READ_LT) or exclusive (WRITE_LT) b yte-range | |||
lock on the byte-range it wishes to READ from or WRITE to. If there is n o | lock on the byte-range it wishes to READ from or WRITE to. If there is n o | |||
appropriate lock, the server checks if there is a conflicting lock | appropriate lock, the server checks if there is a conflicting lock | |||
(which can be done by attempting to acquire the conflicting lock on | (which can be done by attempting to acquire the conflicting lock on | |||
behalf of the lock-owner, and if successful, release the lock after | behalf of the lock-owner, and if successful, release the lock after | |||
the READ or WRITE operation is done), and if there is, the server return s | the READ or WRITE operation is done), and if there is, the server return s | |||
NFS4ERR_LOCKED. | NFS4ERR_LOCKED. | |||
</t> | </t> | |||
<t> | <t> | |||
For Windows environments, byte-range locks are always mandatory, so the | For Windows environments, byte-range locks are always mandatory, so the | |||
server always checks for byte-range locks during I/O requests. | server always checks for byte-range locks during I/O requests. | |||
</t> | </t> | |||
<t> | <t> | |||
Thus, the LOCK operation does not need to distinguish | Thus, the LOCK operation does not need to distinguish | |||
between advisory and mandatory byte-range locks. It is the | between advisory and mandatory byte-range locks. It is the | |||
server's processing of the READ and WRITE operations that introduces | server's processing of the READ and WRITE operations that introduces | |||
the distinction. | the distinction. | |||
</t> | </t> | |||
<t> | <t> | |||
Every stateid that is validly passed to READ, WRITE, or SETATTR, | Every stateid that is validly passed to READ, WRITE, or SETATTR, | |||
with the exception of special stateid values, | with the exception of special stateid values, | |||
defines an access mode for the file (i.e., | defines an access mode for the file (i.e., | |||
OPEN4_SHARE_ACCESS_READ, OPEN4_SHARE_ACCESS_WRITE, or | OPEN4_SHARE_ACCESS_READ, OPEN4_SHARE_ACCESS_WRITE, or | |||
OPEN4_SHARE_ACCESS_BOTH). | OPEN4_SHARE_ACCESS_BOTH). | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
For stateids associated with opens, this is the mode defined by | For stateids associated with opens, this is the mode defined by | |||
the original OPEN that caused the | the original OPEN that caused the | |||
allocation of the OPEN stateid | allocation of the OPEN stateid | |||
and as modified by subsequent OPENs and OPEN_DOWNGRADEs for the | and as modified by subsequent OPENs and OPEN_DOWNGRADEs for the | |||
same open-owner/file pair. | same open-owner/file pair. | |||
</t> | </li> | |||
<t> | <li> | |||
For stateids returned by byte-range LOCK operations, | For stateids returned by byte-range LOCK operations, | |||
the appropriate mode is the access mode for the OPEN | the appropriate mode is the access mode for the OPEN | |||
stateid associated with the lock set represented by the stateid. | stateid associated with the lock set represented by the stateid. | |||
</t> | </li> | |||
<t> | <li> | |||
For delegation stateids, the access mode is based on the type of del egation. | For delegation stateids, the access mode is based on the type of del egation. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
When a READ, WRITE, or SETATTR (that specifies the | When a READ, WRITE, or SETATTR (that specifies the | |||
size attribute) operation is done, the operation is subject to checking against | size attribute) operation is done, the operation is subject to checking against | |||
the access mode to verify that the operation is appropriate given the | the access mode to verify that the operation is appropriate given the | |||
stateid with which the operation is associated. | stateid with which the operation is associated. | |||
</t> | </t> | |||
<t> | <t> | |||
In the case of WRITE-type operations (i.e., WRITEs and SETATTRs that | In the case of WRITE-type operations (i.e., WRITEs and SETATTRs that | |||
set size), the server MUST verify that the access mode allows writing | set size), the server <bcp14>MUST</bcp14> verify that the access mode al | |||
and MUST return an NFS4ERR_OPENMODE error if it does not. In the case o | lows writing | |||
f | and <bcp14>MUST</bcp14> return an NFS4ERR_OPENMODE error if it does not. | |||
In the case of | ||||
READ, the server may perform the corresponding check on the access | READ, the server may perform the corresponding check on the access | |||
mode, or it may choose to allow READ on OPENs for OPEN4_SHARE_ACCESS_WRI TE, to | mode, or it may choose to allow READ on OPENs for OPEN4_SHARE_ACCESS_WRI TE, to | |||
accommodate clients whose WRITE implementation may unavoidably do | accommodate clients whose WRITE implementation may unavoidably do | |||
reads (e.g., due to buffer cache constraints). However, even if READs | reads (e.g., due to buffer cache constraints). However, even if READs | |||
are allowed in these circumstances, the server MUST still check for | are allowed in these circumstances, the server <bcp14>MUST</bcp14> still check for | |||
locks that conflict with the READ (e.g., another OPEN specified OPEN4_SH ARE_DENY_READ or OPEN4_SHARE_DENY_BOTH). Note that a server that does enforce t he access mode check | locks that conflict with the READ (e.g., another OPEN specified OPEN4_SH ARE_DENY_READ or OPEN4_SHARE_DENY_BOTH). Note that a server that does enforce t he access mode check | |||
on READs need not explicitly check for conflicting share reservations | on READs need not explicitly check for conflicting share reservations | |||
since the existence of OPEN for OPEN4_SHARE_ACCESS_READ guarantees that no | since the existence of OPEN for OPEN4_SHARE_ACCESS_READ guarantees that no | |||
conflicting share reservation can exist. | conflicting share reservation can exist. | |||
</t> | </t> | |||
<t> | <t> | |||
The READ bypass special stateid (all bits of "other" and "seqid" set | The READ bypass special stateid (all bits of "other" and "seqid" set | |||
to one) | to one) | |||
indicates a desire to bypass locking checks. The server MAY | indicates a desire to bypass locking checks. The server <bcp14>MAY</bcp 14> | |||
allow READ operations to bypass | allow READ operations to bypass | |||
locking checks at the server, when this special stateid is used. | locking checks at the server, when this special stateid is used. | |||
However, WRITE operations with | However, WRITE operations with | |||
this special stateid value MUST NOT bypass locking checks and are | this special stateid value <bcp14>MUST NOT</bcp14> bypass locking checks and are | |||
treated exactly the same as if a special stateid for anonymous state | treated exactly the same as if a special stateid for anonymous state | |||
were used. | were used. | |||
</t> | </t> | |||
<t> | <t> | |||
A lock may not be granted while a READ or WRITE operation using one of | A lock may not be granted while a READ or WRITE operation using one of | |||
the special stateids is being performed and the scope of the lock | the special stateids is being performed and the scope of the lock | |||
to be granted would conflict with the READ or WRITE operation. | to be granted would conflict with the READ or WRITE operation. | |||
This can occur when: | This can occur when: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
A mandatory byte-range lock is requested with a byte-range that | A mandatory byte-range lock is requested with a byte-range that | |||
conflicts with the byte-range of the READ or WRITE operation. | conflicts with the byte-range of the READ or WRITE operation. | |||
For the purposes of this paragraph, a conflict occurs when | For the purposes of this paragraph, a conflict occurs when | |||
a shared lock is requested and a WRITE operation is being | a shared lock is requested and a WRITE operation is being | |||
performed, or an exclusive lock is requested and either a | performed, or an exclusive lock is requested and either a | |||
READ or a WRITE operation is being performed. | READ or a WRITE operation is being performed. | |||
</t> | </li> | |||
<t> | <li> | |||
A share reservation is requested that denies reading and/or | A share reservation is requested that denies reading and/or | |||
writing and the corresponding operation is being performed. | writing and the corresponding operation is being performed. | |||
</t> | </li> | |||
<t> | <li> | |||
A delegation is to be granted and the delegation type would | A delegation is to be granted and the delegation type would | |||
prevent the I/O operation, i.e., READ and WRITE conflict with | prevent the I/O operation, i.e., READ and WRITE conflict with | |||
an OPEN_DELEGATE_WRITE delegation and WRITE conflicts with an OPEN_D ELEGATE_READ delegation. | an OPEN_DELEGATE_WRITE delegation and WRITE conflicts with an OPEN_D ELEGATE_READ delegation. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
When a client holds a delegation, it needs to ensure | When a client holds a delegation, it needs to ensure | |||
that the stateid sent conveys the association of | that the stateid sent conveys the association of | |||
operation with the delegation, to avoid the delegation from | operation with the delegation, to avoid the delegation from | |||
being avoidably recalled. When the delegation stateid, | being avoidably recalled. When the delegation stateid, | |||
a stateid open associated with that delegation, or a stateid | a stateid open associated with that delegation, or a stateid | |||
representing byte-range locks derived from such an open is | representing byte-range locks derived from such an open is | |||
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> <!-- "Use of the Stateid and Locking" --> | </section> | |||
</section> <!-- "Opens and Byte-Range Locks" --> | </section> | |||
<section title="Lock Ranges" > | <section numbered="true" toc="default"> | |||
<t> | <name>Lock Ranges</name> | |||
<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 | |||
sub-range lock semantics. In the event that a server receives a | sub-range lock semantics. In the event that a server receives a | |||
locking request that represents a sub-range of current locking state | locking request that represents a sub-range of current locking state | |||
for the lock-owner, the server is allowed to return the error | for the lock-owner, the server is allowed to return the error | |||
NFS4ERR_LOCK_RANGE to signify that it does not support sub-range lock | NFS4ERR_LOCK_RANGE to signify that it does not support sub-range lock | |||
operations. Therefore, the client should be prepared to receive this | operations. Therefore, the client should be prepared to receive this | |||
error and, if appropriate, report the error to the requesting | error and, if appropriate, report the error to the requesting | |||
application. | application. | |||
</t> | </t> | |||
<t> | <t> | |||
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" />, 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> <!-- "Lock Ranges" --> | </section> | |||
<section title="Upgrading and Downgrading Locks" > | <section numbered="true" toc="default"> | |||
<t> | <name>Upgrading and Downgrading Locks</name> | |||
<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> | |||
<t> | <t> | |||
If a client has a READ_LT lock on a byte-range, it can request an atomic | If a client has a READ_LT lock on a byte-range, it can request an atomic | |||
upgrade of the lock to a WRITE_LT lock via the LOCK operation by setting | upgrade of the lock to a WRITE_LT lock via the LOCK operation by setting | |||
the type to WRITE_LT or WRITEW_LT. If the server does not support | the type to WRITE_LT or WRITEW_LT. If the server does not support | |||
atomic upgrade, it will return NFS4ERR_LOCK_NOTSUPP. If the upgrade | atomic upgrade, it will return NFS4ERR_LOCK_NOTSUPP. If the upgrade | |||
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> <!-- "Upgrading and Downgrading Locks" --> | </section> | |||
<section title="Stateid Seqid Values and Byte-Range Locks" | <section anchor="byte_range_seqid" numbered="true" toc="default"> | |||
anchor="byte_range_seqid" > | <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 MUST 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 | |||
to the locking status of any byte offset as described by | to the locking status of any byte offset as described by | |||
any of the locks covered by the stateid. A change in locking | any of the locks covered by the stateid. A change in locking | |||
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 MAY increment the "seqid" value. | server <bcp14>MAY</bcp14> increment the "seqid" value. | |||
</t> | </t> | |||
</section> <!-- "Stateid Sequence Values and Byte-Range Locks" --> | </section> | |||
<section title="Issues with Multiple Open-Owners" | <section anchor="multiple_openowners" numbered="true" toc="default"> | |||
anchor="multiple_openowners" > | <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 | |||
arise in which there are multiple stateids, each | arise in which there are multiple stateids, each | |||
representing byte-range locks on the same file and | representing byte-range locks on the same file and | |||
held by the same lock-owner but each associated with | held by the same lock-owner but each associated with | |||
a different open-owner. | a different open-owner. | |||
</t> | </t> | |||
<t> | <t> | |||
In such a situation, the locking status of each byte | In such a situation, the locking status of each byte | |||
(i.e., whether it is locked, the READ_LT or WRITE_LT type of | (i.e., whether it is locked, the READ_LT or WRITE_LT type of | |||
the lock, and the lock-owner holding the lock) MUST | the lock, and the lock-owner holding the lock) <bcp14>MUST</bcp14> | |||
reflect the last LOCK or LOCKU operation done for the | reflect the last LOCK or LOCKU operation done for the | |||
lock-owner in question, independent of the stateid through | lock-owner in question, independent of the stateid through | |||
which the request was sent. | which the request was sent. | |||
</t> | </t> | |||
<t> | <t> | |||
When a byte is locked by the lock-owner in question, the | When a byte is locked by the lock-owner in question, the | |||
open-owner to which that byte-range lock is assigned SHOULD be that | open-owner to which that byte-range lock is assigned <bcp14>SHOULD</bcp14> be that | |||
of the open-owner associated with the stateid through | of the open-owner associated with the stateid through | |||
which the last LOCK of that byte was done. When there | which the last LOCK of that byte was done. When there | |||
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 MUST 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 MUST NOT be incremented. | for that stateid <bcp14>MUST NOT</bcp14> be incremented. | |||
</t> | </t> | |||
</section> <!-- "Issues with Multiple Open-Owners" --> | </section> | |||
<section title="Blocking Locks" anchor="blocking_locks" > | <section anchor="blocking_locks" numbered="true" toc="default"> | |||
<t> | <name>Blocking Locks</name> | |||
<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 OPTIONAL 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 | |||
callback is not used, the server should maintain an ordered | callback is not used, the server should maintain an ordered | |||
list of pending blocking locks. When the conflicting lock is | list of pending blocking locks. When the conflicting lock is | |||
released, the server may wait for the period of time equal to | released, the server may wait for the period of time equal to | |||
lease_time for the first waiting | lease_time for the first waiting | |||
client to re-request the lock. After the lease period expires, the | client to re-request the lock. After the lease period expires, the | |||
next waiting client request is allowed the lock. Clients are required | next waiting client request is allowed the lock. Clients are required | |||
to poll at an interval sufficiently small that it is likely to acquire | to poll at an interval sufficiently small that it is likely to acquire | |||
the lock in a timely manner. The server is not required to maintain a | the lock in a timely manner. The server is not required to maintain a | |||
list of pending blocked locks as it is used to increase fairness and | list of pending blocked locks as it is used to increase fairness and | |||
not correct operation. Because of the unordered nature of crash | not correct operation. Because of the unordered nature of crash | |||
recovery, storing of lock state to stable storage would be required to | recovery, storing of lock state to stable storage would be required to | |||
guarantee ordered granting of blocking locks. | guarantee ordered granting of blocking locks. | |||
</t> | </t> | |||
<t> | <t> | |||
Servers may also note the lock types and delay returning denial of the | Servers may also note the lock types and delay returning denial of the | |||
request to allow extra time for a conflicting lock to be released, | request to allow extra time for a conflicting lock to be released, | |||
allowing a successful return. In this way, clients can avoid the | allowing a successful return. In this way, clients can avoid the | |||
burden of needless frequent polling for blocking locks. The server | burden of needless frequent polling for blocking locks. The server | |||
should take care in the length of delay in the event the client | should take care in the length of delay in the event the client | |||
retransmits the request. | retransmits the request. | |||
</t> | </t> | |||
<t> | <t> | |||
If a server receives a blocking LOCK operation, denies it, and then | If a server receives a blocking LOCK operation, denies it, and then | |||
later receives a nonblocking request for the same lock, which is | later receives a nonblocking request for the same lock, which is | |||
also denied, then it should remove the lock in question from its list of | also denied, then it should remove the lock in question from its list of | |||
pending blocking locks. Clients should use such a nonblocking request | pending blocking locks. Clients should use such a nonblocking request | |||
to indicate to the server that this is the last time they intend to poll | to indicate to the server that this is the last time they intend to poll | |||
for the lock, as may happen when the process requesting the lock is | for the lock, as may happen when the process requesting the lock is | |||
interrupted. This is a courtesy to the server, to prevent it from | interrupted. This is a courtesy to the server, to prevent it from | |||
unnecessarily waiting a lease period before granting other LOCK operations . | unnecessarily waiting a lease period before granting other LOCK operations . | |||
However, clients are not required to perform this courtesy, and servers | However, clients are not required to perform this courtesy, and servers | |||
must not depend on them doing so. Also, clients must be prepared for | must not depend on them doing so. Also, clients must be prepared for | |||
the possibility that this final locking request will be accepted. | the possibility that this final locking request will be accepted. | |||
</t> | </t> | |||
<t> | <t> | |||
When a server indicates, via the flag OPEN4_RESULT_MAY_NOTIFY_LOCK, that | When a server indicates, via the flag OPEN4_RESULT_MAY_NOTIFY_LOCK, that | |||
CB_NOTIFY_LOCK callbacks might be done for the current open file, the | CB_NOTIFY_LOCK callbacks might be done for the current open file, the | |||
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 u nder | should be aware that other clients may be polling and that the server is u nder | |||
no obligation to reserve the lock for that particular client. | no obligation to reserve the lock for that particular client. | |||
</t> | </t> | |||
</section> <!-- title="Blocking Locks" --> | </section> | |||
<section anchor="share_reserve" title="Share Reservations" > | <section anchor="share_reserve" numbered="true" toc="default"> | |||
<t> | <name>Share Reservations</name> | |||
<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> | |||
<figure> | <sourcecode type="pseudocode"><![CDATA[ | |||
<artwork> | ||||
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); | return (NFS4ERR_OK);]]></sourcecode> | |||
</artwork> | <t> | |||
</figure> | ||||
<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> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
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; | const OPEN4_SHARE_DENY_BOTH = 0x00000003;]]></sourcecode> | |||
</artwork> | </section> | |||
</figure> | <section numbered="true" toc="default"> | |||
</section> <!-- "Share Reservations" --> | <name>OPEN/CLOSE Operations</name> | |||
<section title="OPEN/CLOSE Operations" > | <t> | |||
<t> | To provide correct share semantics, a client <bcp14>MUST</bcp14> use the O | |||
To provide correct share semantics, a client MUST use the OPEN | PEN | |||
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 | |||
have a deny mode built into their programming interfaces for opening | have a deny mode built into their programming interfaces for opening | |||
a file should request a deny mode of | a file should request a deny mode of | |||
OPEN4_SHARE_DENY_NONE. | OPEN4_SHARE_DENY_NONE. | |||
</t> | </t> | |||
<t> | <t> | |||
The OPEN operation with the CREATE flag also subsumes the CREATE | The OPEN operation with the CREATE flag also subsumes the CREATE | |||
operation for regular files as used in previous versions of the NFS | operation for regular files as used in previous versions of the NFS | |||
protocol. This allows a create with a share to be done atomically. | protocol. This allows a create with a share to be done atomically. | |||
</t> | </t> | |||
<t> | <t> | |||
The CLOSE operation removes all share reservations held by the | The CLOSE operation removes all share reservations held by the | |||
open-owner on that file. If byte-range locks are held, the client | open-owner on that file. If byte-range locks are held, the client | |||
SHOULD release all locks before sending a CLOSE operation. The server MAY free | <bcp14>SHOULD</bcp14> release all locks before sending a CLOSE operation. The server <bcp14>MAY</bcp14> free | |||
all outstanding locks on CLOSE, but some servers may not support the | all outstanding locks on CLOSE, but some servers may not support the | |||
CLOSE of a file that still has byte-range locks held. The server MUST | CLOSE of a file that still has byte-range locks held. The server <bcp14>M UST</bcp14> | |||
return failure, NFS4ERR_LOCKS_HELD, if any locks would exist after the | return failure, NFS4ERR_LOCKS_HELD, if any locks would exist after the | |||
CLOSE. | CLOSE. | |||
</t> | </t> | |||
<t> | <t> | |||
The LOOKUP operation will return a filehandle without establishing any | The LOOKUP operation will return a filehandle without establishing any | |||
lock state on the server. Without a valid stateid, the server will | lock state on the server. Without a valid stateid, the server will | |||
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> <!-- "OPEN/CLOSE Operations" --> | </section> | |||
<section title="Open Upgrade and Downgrade" anchor="open_upgrade" > | <section anchor="open_upgrade" numbered="true" toc="default"> | |||
<t> | <name>Open Upgrade and Downgrade</name> | |||
<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 | |||
is represented by a single stateid whose "other" value matches | is represented by a single stateid whose "other" value matches | |||
that of the original open, and whose "seqid" value is incremented | that of the original open, and whose "seqid" value is incremented | |||
to reflect the occurrence of the upgrade. The increment is required | to reflect the occurrence of the upgrade. The increment is required | |||
skipping to change at line 12486 ¶ | skipping to change at line 12758 ¶ | |||
is done for read when the existing open file is opened for | is done for read when the existing open file is opened for | |||
OPEN4_SHARE_ACCESS_BOTH). Only a single CLOSE will be done to reset the | OPEN4_SHARE_ACCESS_BOTH). Only a single CLOSE will be done to reset the | |||
effects of both OPENs. The client may use the stateid returned | effects of both OPENs. The client may use the stateid returned | |||
by the OPEN effecting the upgrade or with a stateid sharing the | by the OPEN effecting the upgrade or with a stateid sharing the | |||
same "other" field and a seqid of zero, | same "other" field and a seqid of zero, | |||
although care needs to be taken as far as upgrades that happen | although care needs to be taken as far as upgrades that happen | |||
while the CLOSE is pending. Note that the | while the CLOSE is pending. Note that the | |||
client, when sending the OPEN, may not know that the same file is in | client, when sending the OPEN, may not know that the same file is in | |||
fact being opened. The above only applies if both OPENs result in | fact being opened. The above only applies if both OPENs result in | |||
the OPENed object being designated by the same filehandle. | the OPENed object being designated by the same filehandle. | |||
</t> | </t> | |||
<t> | <t> | |||
When the server chooses to export multiple filehandles corresponding | When the server chooses to export multiple filehandles corresponding | |||
to the same file object and returns different filehandles on two | to the same file object and returns different filehandles on two | |||
different OPENs of the same file object, the server MUST NOT "OR" | different OPENs of the same file object, the server <bcp14>MUST NOT</bcp14 > "OR" | |||
together the access and deny bits and coalesce the two open files. | together the access and deny bits and coalesce the two open files. | |||
Instead, the server must maintain separate OPENs with separate | Instead, the server must maintain separate OPENs with separate | |||
stateids and will require separate CLOSEs to free them. | stateids and will require separate CLOSEs to free them. | |||
</t> | </t> | |||
<t> | <t> | |||
When multiple open files on the client are merged into a single OPEN | When multiple open files on the client are merged into a single OPEN | |||
file object on the server, the close of one of the open files (on the | file object on the server, the close of one of the open files (on the | |||
client) may necessitate change of the access and deny status of the | client) may necessitate change of the access and deny status of the | |||
open file on the server. This is because the union of the access and | open file on the server. This is because the union of the access and | |||
deny bits for the remaining opens may be smaller (i.e., a proper | deny bits for the remaining opens may be smaller (i.e., a proper | |||
subset) than previously. The OPEN_DOWNGRADE operation is used to 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 MUST be incremented, even in situations in which there is | stateid <bcp14>MUST</bcp14> be incremented, even in situations in which th ere 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> <!-- "Open Upgrade and Downgrade" --> | </section> | |||
<section title="Parallel OPENs" anchor="parallel_opens"> | <section anchor="parallel_opens" numbered="true" toc="default"> | |||
<t> | <name>Parallel OPENs</name> | |||
<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 | |||
client once the operations complete. | client once the operations complete. | |||
</t> | </t> | |||
<t> | <t> | |||
In this situation, clients may determine the order in which the | In this situation, clients may determine the order in which the | |||
OPENs were performed by examining the stateids returned by the OPENs. | OPENs were performed by examining the stateids returned by the OPENs. | |||
Stateids that share a common value of the "other" field can be | Stateids that share a common value of the "other" field can be | |||
recognized as having opened the same file, with the order of the | recognized as having opened the same file, with the order of the | |||
operations determinable from the order of the "seqid" fields, mod | operations determinable from the order of the "seqid" fields, mod | |||
any possible wraparound of the 32-bit field. | any possible wraparound of the 32-bit field. | |||
</t> | </t> | |||
<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> <!-- "Parallel OPENs" --> | </section> | |||
<section title="Reclaim of Open and Byte-Range Locks" anchor="open_br_reclaim" | <section anchor="open_br_reclaim" numbered="true" toc="default"> | |||
> | <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. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
To reclaim existing opens, an OPEN operation is performed | To reclaim existing opens, an OPEN operation is performed | |||
using a CLAIM_PREVIOUS. Because the client, in this type | using a CLAIM_PREVIOUS. Because the client, in this type | |||
of situation, will have already opened the file and have | of situation, will have already opened the file and have | |||
the filehandle of the target file, this operation requires | the filehandle of the target file, this operation requires | |||
that the current filehandle be the target file, rather than | that the current filehandle be the target file, rather than | |||
a directory, and no file name is specified. | a directory, and no file name is specified. | |||
</t> | </li> | |||
<t> | <li> | |||
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. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Reclaims of opens associated with delegations are discussed in | Reclaims of opens associated with delegations are discussed in | |||
<xref target="delegation_recovery" />. | <xref target="delegation_recovery" format="default"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> <!-- "File Locking and Share Reservations" --> | </section> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section numbered="true" toc="default"> | |||
$ --> | <name>Client-Side Caching</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <t> | |||
<!-- Copyright (C) The Internet Society (2006) --> | ||||
<section title="Client-Side Caching" > | ||||
<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 | |||
specifications, and it is often unclear what is valid or invalid client | specifications, and it is often unclear what is valid or invalid client | |||
behavior. | behavior. | |||
</t> | </t> | |||
<t> | <t> | |||
The NFSv4.1 protocol uses many techniques similar to those that | The NFSv4.1 protocol uses many techniques similar to those that | |||
have been used in previous protocol versions. The NFSv4.1 | have been used in previous protocol versions. The NFSv4.1 | |||
protocol does not provide distributed cache coherence. However, it | protocol does not provide distributed cache coherence. However, it | |||
defines a more limited set of caching guarantees to allow locks and | defines a more limited set of caching guarantees to allow locks and | |||
share reservations to be used without destructive interference from | share reservations to be used without destructive interference from | |||
client-side caching. | client-side caching. | |||
</t> | </t> | |||
<t> | <t> | |||
In addition, the NFSv4.1 protocol introduces a delegation | In addition, the NFSv4.1 protocol introduces a delegation | |||
mechanism, which allows many decisions normally made by the server to | mechanism, which allows many decisions normally made by the server to | |||
be made locally by clients. This mechanism provides efficient support | be made locally by clients. This mechanism provides efficient support | |||
of the common cases where sharing is infrequent or where sharing is | of the common cases where sharing is infrequent or where sharing is | |||
read-only. | read-only. | |||
</t> | </t> | |||
<section title="Performance Challenges for Client-Side Caching" > | <section numbered="true" toc="default"> | |||
<t> | <name>Performance Challenges for Client-Side Caching</name> | |||
<t> | ||||
Caching techniques used in previous versions of the NFS protocol have | Caching techniques used in previous versions of the NFS protocol have | |||
been successful in providing good performance. However, several | been successful in providing good performance. However, several | |||
scalability challenges can arise when those techniques are used with | scalability challenges can arise when those techniques are used with | |||
very large numbers of clients. This is particularly true when clients | very large numbers of clients. This is particularly true when clients | |||
are geographically distributed, which classically increases the latency | are geographically distributed, which classically increases the latency | |||
for cache revalidation requests. | for cache revalidation requests. | |||
</t> | </t> | |||
<t> | <t> | |||
The previous versions of the NFS protocol repeat their file data cache | The previous versions of the NFS protocol repeat their file data cache | |||
validation requests at the time the file is opened. This behavior can | validation requests at the time the file is opened. This behavior can | |||
have serious performance drawbacks. A common case is one in which a | have serious performance drawbacks. A common case is one in which a | |||
file is only accessed by a single client. Therefore, sharing is | file is only accessed by a single client. Therefore, sharing is | |||
infrequent. | infrequent. | |||
</t> | </t> | |||
<t> | <t> | |||
In this case, repeated references to the server to find that no | In this case, repeated references to the server to find that no | |||
conflicts exist are expensive. A better option with regards to | conflicts exist are expensive. A better option with regards to | |||
performance is to allow a client that repeatedly opens a file to do so | performance is to allow a client that repeatedly opens a file to do so | |||
without reference to the server. This is done until potentially | without reference to the server. This is done until potentially | |||
conflicting operations from another client actually occur. | conflicting operations from another client actually occur. | |||
</t> | </t> | |||
<t> | <t> | |||
A similar situation arises in connection with byte-range locking. Sending | A similar situation arises in connection with byte-range locking. Sending | |||
LOCK and LOCKU operations as well as the READ and | LOCK and LOCKU operations as well as the READ and | |||
WRITE operations necessary to make data caching consistent with the | WRITE operations necessary to make data caching consistent with the | |||
locking semantics (see <xref target="dc_file_locking" />) | locking semantics (see <xref target="dc_file_locking" format="default"/>) | |||
can severely limit performance. When locking is used to provide | can severely limit performance. When locking is used to provide | |||
protection against infrequent conflicts, a large penalty is incurred. | protection against infrequent conflicts, a large penalty is incurred. | |||
This penalty may discourage the use of byte-range locking by applications. | This penalty may discourage the use of byte-range locking by applications. | |||
</t> | </t> | |||
<t> | <t> | |||
The NFSv4.1 protocol provides more aggressive caching strategies | The NFSv4.1 protocol provides more aggressive caching strategies | |||
with the following design goals: | with the following design goals: | |||
<list style='symbols'> | ||||
<t> | ||||
Compatibility with a large range of server semantics. | ||||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Compatibility with a large range of server semantics. | ||||
</li> | ||||
<li> | ||||
Providing the same caching benefits as previous versions of | Providing the same caching benefits as previous versions of | |||
the NFS protocol when unable to support the more aggressive model. | the NFS protocol when unable to support the more aggressive model. | |||
</t> | </li> | |||
<t> | <li> | |||
Requirements for aggressive caching are organized so that a | Requirements for aggressive caching are organized so that a | |||
large portion of the benefit can be obtained even when not | large portion of the benefit can be obtained even when not | |||
all of the requirements can be met. | all of the requirements can be met. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The appropriate requirements for the server are discussed in later | The appropriate requirements for the server are discussed in later | |||
sections in which specific forms of caching are covered (see | sections in which specific forms of caching are covered (see | |||
<xref target="open_delegation" />). | <xref target="open_delegation" format="default"/>). | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Delegation and Callbacks" anchor="deleg_and_cb" > | <section anchor="deleg_and_cb" numbered="true" toc="default"> | |||
<t> | <name>Delegation and Callbacks</name> | |||
<t> | ||||
Recallable delegation of server responsibilities for a file to a | Recallable delegation of server responsibilities for a file to a | |||
client improves performance by avoiding repeated requests to the | client improves performance by avoiding repeated requests to the | |||
server in the absence of inter-client conflict. With the use of a | server in the absence of inter-client conflict. With the use of a | |||
"callback" RPC from server to client, a server recalls delegated | "callback" RPC from server to client, a server recalls delegated | |||
responsibilities when another client engages in sharing of a delegated | responsibilities when another client engages in sharing of a delegated | |||
file. | file. | |||
</t> | </t> | |||
<t> | <t> | |||
A delegation is passed from the server to the client, specifying the | A delegation is passed from the server to the client, specifying the | |||
object of the delegation and the type of delegation. There are | object of the delegation and the type of delegation. There are | |||
different types of delegations, but each type contains a stateid to be | different types of delegations, but each type contains a stateid to be | |||
used to represent the delegation when performing operations that | used to represent the delegation when performing operations that | |||
depend on the delegation. This stateid is similar to those associated | depend on the delegation. This stateid is similar to those associated | |||
with locks and share reservations but differs in that the stateid for | with locks and share reservations but differs in that the stateid for | |||
a delegation is associated with a client ID and may be used on behalf | a delegation is associated with a client ID and may be used on behalf | |||
of all the open-owners for the given client. A delegation is made | of all the open-owners for the given client. A delegation is made | |||
to the client as a whole and not to any specific process or thread of | to the client as a whole and not to any specific process or thread of | |||
control within it. | control within it. | |||
</t> | </t> | |||
<t> | <t> | |||
The backchannel is established by CREATE_SESSION and | The backchannel is established by CREATE_SESSION and | |||
BIND_CONN_TO_SESSION, and the client is required | BIND_CONN_TO_SESSION, and the client is required | |||
to maintain it. Because the backchannel may be down, even | to maintain it. Because the backchannel may be down, even | |||
temporarily, | temporarily, | |||
correct protocol operation does not depend on | correct protocol operation does not depend on | |||
them. Preliminary testing of backchannel functionality by means of a | them. Preliminary testing of backchannel functionality by means of a | |||
CB_COMPOUND procedure with a single operation, CB_SEQUENCE, | CB_COMPOUND procedure with a single operation, CB_SEQUENCE, | |||
can be used to check the continuity of the backchannel. A | can be used to check the continuity of the backchannel. A | |||
server avoids delegating responsibilities until it has | server avoids delegating responsibilities until it has | |||
determined that the backchannel exists. Because the granting of a | determined that the backchannel exists. Because the granting of a | |||
delegation is always conditional upon the absence of conflicting | delegation is always conditional upon the absence of conflicting | |||
access, clients MUST NOT assume that a delegation will be granted and | access, clients <bcp14>MUST NOT</bcp14> assume that a delegation will be g | |||
they MUST always be prepared for OPENs, WANT_DELEGATIONs, and | ranted and | |||
they <bcp14>MUST</bcp14> always be prepared for OPENs, WANT_DELEGATIONs, a | ||||
nd | ||||
GET_DIR_DELEGATIONs to be processed without any | GET_DIR_DELEGATIONs to be processed without any | |||
delegations being granted. | delegations being granted. | |||
</t> | </t> | |||
<t> | <t> | |||
Unlike locks, an operation by a second client to a delegated file will | Unlike locks, an operation by a second client to a delegated file will | |||
cause the server to recall a delegation through a callback. For | cause the server to recall a delegation through a callback. For | |||
individual operations, we will describe, under IMPLEMENTATION, when | individual operations, we will describe, under IMPLEMENTATION, when | |||
such operations are required to effect a recall. A number of | such operations are required to effect a recall. A number of | |||
points should be noted, however. | points should be noted, however. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The server is free to recall a delegation | The server is free to recall a delegation | |||
whenever it feels it is desirable and may do so even if no | whenever it feels it is desirable and may do so even if no | |||
operations requiring recall are being done. | operations requiring recall are being done. | |||
</t> | </li> | |||
<t> | <li> | |||
Operations done outside the NFSv4.1 protocol, due to, for | Operations done outside the NFSv4.1 protocol, due to, for | |||
example, access by other protocols, or by local access, | example, access by other protocols, or by local access, | |||
also need to result in delegation recall when they make | also need to result in delegation recall when they make | |||
analogous changes to file system data. What is crucial | analogous changes to file system data. What is crucial | |||
is if the change would invalidate the guarantees provided | is if the change would invalidate the guarantees provided | |||
by the delegation. When this is possible, the | by the delegation. When this is possible, the | |||
delegation needs to be recalled and MUST be returned or | delegation needs to be recalled and <bcp14>MUST</bcp14> be returned or | |||
revoked before allowing the operation to proceed. | revoked before allowing the operation to proceed. | |||
</t> | </li> | |||
<t> | <li> | |||
The semantics of the file system are crucial in defining | The semantics of the file system are crucial in defining | |||
when delegation recall is required. If a particular change | when delegation recall is required. If a particular change | |||
within a specific implementation causes change to a | within a specific implementation causes change to a | |||
file attribute, then delegation recall is required, whether | file attribute, then delegation recall is required, whether | |||
that operation has been specifically listed as requiring | that operation has been specifically listed as requiring | |||
delegation recall. Again, what is critical is whether the | delegation recall. Again, what is critical is whether the | |||
guarantees provided by the delegation are being invalidated. | guarantees provided by the delegation are being invalidated. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Despite those caveats, the implementation sections for a number | Despite those caveats, the implementation sections for a number | |||
of operations describe situations in which delegation recall | of operations describe situations in which delegation recall | |||
would be required under some common circumstances: | would be required under some common circumstances: | |||
<list style="symbols"> | ||||
<t> | ||||
For GETATTR, see <xref target="OP_GETATTR_IMPLEMENTATION" />. | ||||
</t> | ||||
<t> | ||||
For OPEN, see <xref target="OP_OPEN_IMPLEMENTATION" />. | ||||
</t> | ||||
<t> | ||||
For READ, see <xref target="OP_READ_IMPLEMENTATION" />. | ||||
</t> | ||||
<t> | ||||
For REMOVE, see <xref target="OP_REMOVE_IMPLEMENTATION" />. | ||||
</t> | ||||
<t> | ||||
For RENAME, see <xref target="OP_RENAME_IMPLEMENTATION" />. | ||||
</t> | ||||
<t> | ||||
For SETATTR, see <xref target="OP_SETATTR_IMPLEMENTATION" />. | ||||
</t> | </t> | |||
<ul spacing="normal"> | ||||
<li> | ||||
For GETATTR, see <xref target="OP_GETATTR_IMPLEMENTATION" format="defa | ||||
ult"/>. | ||||
</li> | ||||
<li> | ||||
For OPEN, see <xref target="OP_OPEN_IMPLEMENTATION" format="default"/> | ||||
. | ||||
</li> | ||||
<li> | ||||
For READ, see <xref target="OP_READ_IMPLEMENTATION" format="default"/> | ||||
. | ||||
</li> | ||||
<li> | ||||
For REMOVE, see <xref target="OP_REMOVE_IMPLEMENTATION" format="defaul | ||||
t"/>. | ||||
</li> | ||||
<li> | ||||
For RENAME, see <xref target="OP_RENAME_IMPLEMENTATION" format="defaul | ||||
t"/>. | ||||
</li> | ||||
<li> | ||||
For SETATTR, see <xref target="OP_SETATTR_IMPLEMENTATION" format="defa | ||||
ult"/>. | ||||
</li> | ||||
<li> | ||||
For WRITE, see <xref target="OP_WRITE_IMPLEMENTATION" format="default" | ||||
/>. | ||||
</li> | ||||
</ul> | ||||
<t> | <t> | |||
For WRITE, see <xref target="OP_WRITE_IMPLEMENTATION" />. | ||||
</t> | ||||
</list> | ||||
</t> | ||||
<t> | ||||
On recall, the client holding the delegation needs to flush modified | On recall, the client holding the delegation needs to flush modified | |||
state (such as modified data) to the server and return the | state (such as modified data) to the server and return the | |||
delegation. The conflicting request will not be acted on until | delegation. The conflicting request will not be acted on until | |||
the recall is complete. The recall is considered complete when | the recall is complete. The recall is considered complete when | |||
the client returns the delegation or the server times its wait | the client returns the delegation or the server times its wait | |||
for the delegation to be returned and revokes the delegation as | for the delegation to be returned and revokes the delegation as | |||
a result of the timeout. In the interim, the server will either | a result of the timeout. In the interim, the server will either | |||
delay responding to conflicting requests or respond to them with | delay responding to conflicting requests or respond to them with | |||
NFS4ERR_DELAY. Following the resolution of the recall, the | NFS4ERR_DELAY. Following the resolution of the recall, the | |||
server has the information necessary to grant or deny the second | server has the information necessary to grant or deny the second | |||
client's request. | client's request. | |||
</t> | </t> | |||
<t> | <t> | |||
At the time the client receives a delegation recall, it may have | At the time the client receives a delegation recall, it may have | |||
substantial state that needs to be flushed to the server. Therefore, | substantial state that needs to be flushed to the server. Therefore, | |||
the server should allow sufficient time for the delegation to be | the server should allow sufficient time for the delegation to be | |||
returned since it may involve numerous RPCs to the server. If the | returned since it may involve numerous RPCs to the server. If the | |||
server is able to determine that the client is diligently flushing | server is able to determine that the client is diligently flushing | |||
state to the server as a result of the recall, the server may extend | state to the server as a result of the recall, the server may extend | |||
the usual time allowed for a recall. However, the time allowed for | the usual time allowed for a recall. However, the time allowed for | |||
recall completion should not be unbounded. | recall completion should not be unbounded. | |||
</t> | </t> | |||
<t> | <t> | |||
An example of this is when responsibility to mediate opens on a given | An example of this is when responsibility to mediate opens on a given | |||
file is delegated to a client (see <xref target="open_delegation" />). | file is delegated to a client (see <xref target="open_delegation" format=" default"/>). | |||
The server will not know what opens are in effect on the client. | The server will not know what opens are in effect on the client. | |||
Without this knowledge, the server will be unable to determine if the | Without this knowledge, the server will be unable to determine if the | |||
access and deny states for the file allow any particular open until | access and deny states for the file allow any particular open until | |||
the delegation for the file has been returned. | the delegation for the file has been returned. | |||
</t> | </t> | |||
<t> | <t> | |||
A client failure or a network partition can result in failure to | A client failure or a network partition can result in failure to | |||
respond to a recall callback. In this case, the server will revoke the | respond to a recall callback. In this case, the server will revoke the | |||
delegation, which in turn will render useless any modified state still | delegation, which in turn will render useless any modified state still | |||
on the client. | on the client. | |||
</t> | </t> | |||
<section title="Delegation Recovery" | <section anchor="delegation_recovery" numbered="true" toc="default"> | |||
anchor="delegation_recovery" > | <name>Delegation Recovery</name> | |||
<t> | ||||
There are three situations that delegation recovery needs to deal with: | ||||
<list style="symbols"> | ||||
<t> | <t> | |||
client restart | There are three situations that delegation recovery needs to deal with: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
client restart | ||||
</li> | ||||
<li> | ||||
server restart | server restart | |||
</t> | </li> | |||
<t> | <li> | |||
network partition (full or backchannel-only) | network partition (full or backchannel-only) | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
In the event the client restarts, the failure to renew | In the event the client restarts, the failure to renew | |||
the lease will result in the revocation of byte-range locks and share | the lease will result in the revocation of byte-range locks and share | |||
reservations. Delegations, however, may be treated a bit differently. | reservations. Delegations, however, may be treated a bit differently. | |||
</t> | </t> | |||
<t> | <t> | |||
There will be situations in which delegations will need to be | There will be situations in which delegations will need to be | |||
re-established after a client restarts. The reason for this | re-established after a client restarts. The reason for this | |||
is that the client may have file data stored locally and this data was | is that the client may have file data stored locally and this data was | |||
associated with the previously held delegations. The client will need | associated with the previously held delegations. The client will need | |||
to re-establish the appropriate file state on the server. | to re-establish the appropriate file state on the server. | |||
</t> | </t> | |||
<t> | <t> | |||
To allow for this type of client recovery, the server MAY extend the | To allow for this type of client recovery, the server <bcp14>MAY</bcp14> | |||
extend the | ||||
period for delegation recovery beyond the typical lease expiration | period for delegation recovery beyond the typical lease expiration | |||
period. This implies that requests from other clients that conflict | period. This implies that requests from other clients that conflict | |||
with these delegations will need to wait. Because the normal recall | with these delegations will need to wait. Because the normal recall | |||
process may require significant time for the client to flush changed | process may require significant time for the client to flush changed | |||
state to the server, other clients need be prepared for delays that | state to the server, other clients need be prepared for delays that | |||
occur because of a conflicting delegation. This longer interval would | occur because of a conflicting delegation. This longer interval would | |||
increase the window for clients to restart and consult stable storage | increase the window for clients to restart and consult stable storage | |||
so that the delegations can be reclaimed. For OPEN delegations, such | so that the delegations can be reclaimed. For OPEN delegations, such | |||
delegations are reclaimed using OPEN with a claim type of | delegations are reclaimed using OPEN with a claim type of | |||
CLAIM_DELEGATE_PREV or CLAIM_DELEG_PREV_FH (see Sections | CLAIM_DELEGATE_PREV or CLAIM_DELEG_PREV_FH (see Sections | |||
<xref target="data_caching_revocation" format="counter" /> | <xref target="data_caching_revocation" format="counter"/> | |||
and <xref target="OP_OPEN" format="counter" /> for discussion of OPEN de | and <xref target="OP_OPEN" format="counter"/> for discussion of OPEN del | |||
legation | egation | |||
and the details of OPEN, respectively). | and the details of OPEN, respectively). | |||
</t> | </t> | |||
<t> | <t> | |||
A server MAY support claim types of CLAIM_DELEGATE_PREV and | A server <bcp14>MAY</bcp14> support claim types of CLAIM_DELEGATE_PREV a | |||
nd | ||||
CLAIM_DELEG_PREV_FH, and if it | CLAIM_DELEG_PREV_FH, and if it | |||
does, it MUST NOT remove delegations upon a CREATE_SESSION that | does, it <bcp14>MUST NOT</bcp14> remove delegations upon a CREATE_SESSIO N that | |||
confirm a client ID created by EXCHANGE_ID. | confirm a client ID created by EXCHANGE_ID. | |||
Instead, the server MUST, for a period of time no less than that of the value of | Instead, the server <bcp14>MUST</bcp14>, for a period of time no less th an that of the value of | |||
the lease_time attribute, maintain the client's delegations to allow | the lease_time attribute, maintain the client's delegations to allow | |||
time for the client to send CLAIM_DELEGATE_PREV and/or CLAIM_DELEG_PREV_ FH requests. The server | time for the client to send CLAIM_DELEGATE_PREV and/or CLAIM_DELEG_PREV_ FH requests. The server | |||
that supports CLAIM_DELEGATE_PREV and/or CLAIM_DELEG_PREV_FH MUST suppor t the DELEGPURGE | that supports CLAIM_DELEGATE_PREV and/or CLAIM_DELEG_PREV_FH <bcp14>MUST </bcp14> support the DELEGPURGE | |||
operation. | operation. | |||
</t> | </t> | |||
<t> | <t> | |||
When the server restarts, delegations are reclaimed (using | When the server restarts, delegations are reclaimed (using | |||
the OPEN operation with CLAIM_PREVIOUS) in a similar fashion to byte-ran ge | the OPEN operation with CLAIM_PREVIOUS) in a similar fashion to byte-ran ge | |||
locks and share reservations. However, there is a slight semantic | locks and share reservations. However, there is a slight semantic | |||
difference. In the normal case, if the server decides that a | difference. In the normal case, if the server decides that a | |||
delegation should not be granted, it performs the requested action | delegation should not be granted, it performs the requested action | |||
(e.g., OPEN) without granting any delegation. For reclaim, the server | (e.g., OPEN) without granting any delegation. For reclaim, the server | |||
grants the delegation but a special designation is applied so that the | grants the delegation but a special designation is applied so that the | |||
client treats the delegation as having been granted but recalled by | client treats the delegation as having been granted but recalled by | |||
the server. Because of this, the client has the duty to write all | the server. Because of this, the client has the duty to write all | |||
modified state to the server and then return the delegation. This | modified state to the server and then return the delegation. This | |||
process of handling delegation reclaim reconciles three principles of | process of handling delegation reclaim reconciles three principles of | |||
the NFSv4.1 protocol: | the NFSv4.1 protocol: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Upon reclaim, a client reporting resources assigned to it by an | Upon reclaim, a client reporting resources assigned to it by an | |||
earlier server instance must be granted those resources. | earlier server instance must be granted those resources. | |||
</t> | </li> | |||
<t> | <li> | |||
The server has unquestionable authority to determine whether | The server has unquestionable authority to determine whether | |||
delegations are to be granted and, once granted, whether they are to | delegations are to be granted and, once granted, whether they are to | |||
be continued. | be continued. | |||
</t> | </li> | |||
<t> | <li> | |||
The use of callbacks should not be depended upon until the client ha s | The use of callbacks should not be depended upon until the client ha s | |||
proven its ability to receive them. | proven its ability to receive them. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
When a client needs to reclaim a delegation and there is no associated | When a client needs to reclaim a delegation and there is no associated | |||
open, the client may use the CLAIM_PREVIOUS variant of the | open, the client may use the CLAIM_PREVIOUS variant of the | |||
WANT_DELEGATION operation. However, since the server is not required | WANT_DELEGATION operation. However, since the server is not required | |||
to support this operation, an alternative is to reclaim via a dummy OPEN | to support this operation, an alternative is to reclaim via a dummy OPEN | |||
together with the delegation | together with the delegation | |||
using an OPEN of type CLAIM_PREVIOUS. The dummy open file can | using an OPEN of type CLAIM_PREVIOUS. The dummy open file can | |||
be released using a CLOSE to re-establish the original state to be | be released using a CLOSE to re-establish the original state to be | |||
reclaimed, a delegation without an associated open. | reclaimed, a delegation without an associated open. | |||
</t> | </t> | |||
<t> | <t> | |||
When a client has more than a single open associated with a delegation, | When a client has more than a single open associated with a delegation, | |||
state for those additional opens can be established using OPEN | state for those additional opens can be established using OPEN | |||
operations of type CLAIM_DELEGATE_CUR. When these are used to | operations of type CLAIM_DELEGATE_CUR. When these are used to | |||
establish opens associated with reclaimed delegations, the | establish opens associated with reclaimed delegations, the | |||
server MUST allow them when made within the grace period. | server <bcp14>MUST</bcp14> allow them when made within the grace period. | |||
</t> | </t> | |||
<t> | <t> | |||
When a network partition occurs, delegations are subject to freeing by | When a network partition occurs, delegations are subject to freeing by | |||
the server when the lease renewal period expires. This is similar to | the server when the lease renewal period expires. This is similar to | |||
the behavior for locks and share reservations. For delegations, | the behavior for locks and share reservations. For delegations, | |||
however, the server may extend the period in which conflicting | however, the server may extend the period in which conflicting | |||
requests are held off. Eventually, the occurrence of a conflicting | requests are held off. Eventually, the occurrence of a conflicting | |||
request from another client will cause revocation of the delegation. | request from another client will cause revocation of the delegation. | |||
A loss of the backchannel (e.g., by later network configuration | A loss of the backchannel (e.g., by later network configuration | |||
change) will have the same effect. A recall request will fail and | change) will have the same effect. A recall request will fail and | |||
revocation of the delegation will result. | revocation of the delegation will result. | |||
</t> | </t> | |||
<t> | <t> | |||
A client normally finds out about revocation of a delegation when it | A client normally finds out about revocation of a delegation when it | |||
uses a stateid associated with a delegation and receives one of the | uses a stateid associated with a delegation and receives one of the | |||
errors NFS4ERR_EXPIRED, NFS4ERR_ADMIN_REVOKED, or NFS4ERR_DELEG_REVOKED. | errors NFS4ERR_EXPIRED, NFS4ERR_ADMIN_REVOKED, or NFS4ERR_DELEG_REVOKED. | |||
It also may find out about delegation revocation | It also may find out about delegation revocation | |||
after a client restart when it attempts to reclaim a delegation and | after a client restart when it attempts to reclaim a delegation and | |||
receives that same error. Note that in the case of a revoked OPEN_DELEG ATE_WRITE delegation, there are issues because data may have been modified | receives that same error. Note that in the case of a revoked OPEN_DELEG ATE_WRITE delegation, there are issues because data may have been modified | |||
by the client whose delegation is revoked and separately by other | by the client whose delegation is revoked and separately by other | |||
clients. See <xref target="revocation_recovery_write" /> | clients. See <xref target="revocation_recovery_write" format="default"/ > | |||
for a discussion of such issues. Note also that when | for a discussion of such issues. Note also that when | |||
delegations are revoked, information about the revoked delegation will | delegations are revoked, information about the revoked delegation will | |||
be written by the server to stable storage (as described in | be written by the server to stable storage (as described in | |||
<xref target="network_partitions_and_recovery" />). This is done | <xref target="network_partitions_and_recovery" format="default"/>). Thi s is done | |||
to deal with the case in | to deal with the case in | |||
which a server restarts after revoking a delegation but before the | which a server restarts after revoking a delegation but before the | |||
client holding the revoked delegation is notified about the | client holding the revoked delegation is notified about the | |||
revocation. | revocation. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section title="Data Caching" > | <section numbered="true" toc="default"> | |||
<t> | <name>Data Caching</name> | |||
<t> | ||||
When applications share access to a set of files, they need to be | When applications share access to a set of files, they need to be | |||
implemented so as to take account of the possibility of conflicting | implemented so as to take account of the possibility of conflicting | |||
access by another application. This is true whether the applications | access by another application. This is true whether the applications | |||
in question execute on different clients or reside on the same client. | in question execute on different clients or reside on the same client. | |||
</t> | </t> | |||
<t> | <t> | |||
Share reservations and byte-range locks are the facilities the NFSv4.1 pro tocol | Share reservations and byte-range locks are the facilities the NFSv4.1 pro tocol | |||
provides to allow applications to coordinate access by | provides to allow applications to coordinate access by | |||
using mutual exclusion facilities. The NFSv4.1 protocol's | using mutual exclusion facilities. The NFSv4.1 protocol's | |||
data caching must be implemented such that it does not invalidate the | data caching must be implemented such that it does not invalidate the | |||
assumptions on which those using these facilities depend. | assumptions on which those using these facilities depend. | |||
</t> | </t> | |||
<section title="Data Caching and OPENs" > | <section numbered="true" toc="default"> | |||
<t> | <name>Data Caching and OPENs</name> | |||
<t> | ||||
In order to avoid invalidating the sharing assumptions on which | In order to avoid invalidating the sharing assumptions on which | |||
applications rely, NFSv4.1 clients should not provide cached | applications rely, NFSv4.1 clients should not provide cached | |||
data to applications or modify it on behalf of an application when it | data to applications or modify it on behalf of an application when it | |||
would not be valid to obtain or modify that same data via a READ or | would not be valid to obtain or modify that same data via a READ or | |||
WRITE operation. | WRITE operation. | |||
</t> | </t> | |||
<t> | <t> | |||
Furthermore, in the absence of an OPEN delegation | Furthermore, in the absence of an OPEN delegation | |||
(see <xref target="open_delegation" />), | (see <xref target="open_delegation" format="default"/>), | |||
two additional rules apply. Note that these rules are | two additional rules apply. Note that these rules are | |||
obeyed in practice by many NFSv3 clients. | obeyed in practice by many NFSv3 clients. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
First, cached data present on a client must be revalidated after doi ng | First, cached data present on a client must be revalidated after doi ng | |||
an OPEN. Revalidating means that the client fetches the change | an OPEN. Revalidating means that the client fetches the change | |||
attribute from the server, compares it with the cached change | attribute from the server, compares it with the cached change | |||
attribute, and if different, declares the cached data (as well as th e | attribute, and if different, declares the cached data (as well as th e | |||
cached attributes) as invalid. This is to ensure that the data for | cached attributes) as invalid. This is to ensure that the data for | |||
the OPENed file is still correctly reflected in the client's cache. | the OPENed file is still correctly reflected in the client's cache. | |||
This validation must be done at least when the client's OPEN operati on | This validation must be done at least when the client's OPEN operati on | |||
includes a deny of OPEN4_SHARE_DENY_WRITE or | includes a deny of OPEN4_SHARE_DENY_WRITE or | |||
OPEN4_SHARE_DENY_BOTH, thus terminating a period in which | OPEN4_SHARE_DENY_BOTH, thus terminating a period in which | |||
other | other | |||
clients may have had the opportunity to open the file with | clients may have had the opportunity to open the file with | |||
OPEN4_SHARE_ACCESS_WRITE/OPEN4_SHARE_ACCESS_BOTH | OPEN4_SHARE_ACCESS_WRITE/OPEN4_SHARE_ACCESS_BOTH | |||
access. Clients may choose to do the revalidation more often (i.e., at | access. Clients may choose to do the revalidation more often (i.e., at | |||
OPENs specifying a deny mode of OPEN4_SHARE_DENY_NONE) to parallel t he NFSv3 protocol's | OPENs specifying a deny mode of OPEN4_SHARE_DENY_NONE) to parallel t he NFSv3 protocol's | |||
practice for the benefit of users assuming this degree of cache | practice for the benefit of users assuming this degree of cache | |||
revalidation. | revalidation. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
Since the change attribute is updated for data and metadata | Since the change attribute is updated for data and metadata | |||
modifications, some client implementors may be tempted to use the | modifications, some client implementors may be tempted to use the | |||
time_modify attribute and not the change attribute to validate cache d data, so that | time_modify attribute and not the change attribute to validate cache d data, so that | |||
metadata changes do not spuriously invalidate clean data. The | metadata changes do not spuriously invalidate clean data. The | |||
implementor is cautioned in this approach. The change attribute is | implementor is cautioned in this approach. The change attribute is | |||
guaranteed to change for each update to the file, whereas time_modif y | guaranteed to change for each update to the file, whereas time_modif y | |||
is guaranteed to change only at the granularity of the time_delta | is guaranteed to change only at the granularity of the time_delta | |||
attribute. Use by the client's data cache validation logic of | attribute. Use by the client's data cache validation logic of | |||
time_modify and not change runs the risk of the client incorrectly | time_modify and not change runs the risk of the client incorrectly | |||
marking stale data as valid. Thus, any cache validation approach | marking stale data as valid. Thus, any cache validation approach | |||
by the client MUST include the use of the change attribute. | by the client <bcp14>MUST</bcp14> include the use of the change attr | |||
</t> | ibute. | |||
<t> | </t> | |||
</li> | ||||
<li> | ||||
Second, modified data must be flushed to the server before closing a | Second, modified data must be flushed to the server before closing a | |||
file OPENed for OPEN4_SHARE_ACCESS_WRITE. This is complementary to the first rule. If | file OPENed for OPEN4_SHARE_ACCESS_WRITE. This is complementary to the first rule. If | |||
the data is not flushed at CLOSE, the revalidation done | the data is not flushed at CLOSE, the revalidation done | |||
after the client OPENs a file is unable to achieve its | after the client OPENs a file is unable to achieve its | |||
purpose. The other aspect to flushing the data before | purpose. The other aspect to flushing the data before | |||
close is that the data must be committed to stable | close is that the data must be committed to stable | |||
storage, at the server, before the CLOSE operation is | storage, at the server, before the CLOSE operation is | |||
requested by the client. In the case of a server restart and a CLOS Ed | requested by the client. In the case of a server restart and a CLOS Ed | |||
file, it may not be possible to retransmit the data to be written to | file, it may not be possible to retransmit the data to be written to | |||
the file, hence, this requirement. | the file, hence, this requirement. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section anchor="dc_file_locking" numbered="true" toc="default"> | |||
<section title="Data Caching and File Locking" anchor="dc_file_locking"> | <name>Data Caching and File Locking</name> | |||
<t> | <t> | |||
For those applications that choose to use byte-range locking instead of | For those applications that choose to use byte-range locking instead of | |||
share reservations to exclude inconsistent file access, there is an | share reservations to exclude inconsistent file access, there is an | |||
analogous set of constraints that apply to client-side data caching. | analogous set of constraints that apply to client-side data caching. | |||
These rules are effective only if the byte-range locking is used in a wa y | These rules are effective only if the byte-range locking is used in a wa y | |||
that matches in an equivalent way the actual READ and WRITE operations | that matches in an equivalent way the actual READ and WRITE operations | |||
executed. This is as opposed to byte-range locking that is based on pur e | executed. This is as opposed to byte-range locking that is based on pur e | |||
convention. For example, it is possible to manipulate a two-megabyte | convention. For example, it is possible to manipulate a two-megabyte | |||
file by dividing the file into two one-megabyte ranges and protecting | file by dividing the file into two one-megabyte ranges and protecting | |||
access to the two byte-ranges by byte-range locks on bytes zero and one. A WRITE_LT lock on | access to the two byte-ranges by byte-range locks on bytes zero and one. A WRITE_LT lock on | |||
byte zero of the file would represent the right to perform | byte zero of the file would represent the right to perform | |||
READ and WRITE operations on the first byte-range. A WRITE_LT lock on | READ and WRITE operations on the first byte-range. A WRITE_LT lock on | |||
byte one of the file would represent the right to perform READ and WRITE | byte one of the file would represent the right to perform READ and WRITE | |||
operations on the second byte-range. As long as all applications | operations on the second byte-range. As long as all applications | |||
manipulating the file obey this convention, they will work on a local | manipulating the file obey this convention, they will work on a local | |||
file system. However, they may not work with the NFSv4.1 | file system. However, they may not work with the NFSv4.1 | |||
protocol unless clients refrain from data caching. | protocol unless clients refrain from data caching. | |||
</t> | </t> | |||
<t> | ||||
The rules for data caching in the byte-range locking environment are: | ||||
<list style='symbols'> | ||||
<t> | <t> | |||
The rules for data caching in the byte-range locking environment are: | ||||
</t> | ||||
<ul spacing="normal"> | ||||
<li> | ||||
First, when a client obtains a byte-range lock for a particular byte -range, the | First, when a client obtains a byte-range lock for a particular byte -range, the | |||
data cache corresponding to that byte-range (if any cache data exist s) | data cache corresponding to that byte-range (if any cache data exist s) | |||
must be revalidated. If the change attribute indicates that the fil e | must be revalidated. If the change attribute indicates that the fil e | |||
may have been updated since the cached data was obtained, the client | may have been updated since the cached data was obtained, the client | |||
must flush or invalidate the cached data for the newly locked byte-r ange. | must flush or invalidate the cached data for the newly locked byte-r ange. | |||
A client might choose to invalidate all of the non-modified cached d ata | A client might choose to invalidate all of the non-modified cached d ata | |||
that it has for the file, but the only requirement for correct | that it has for the file, but the only requirement for correct | |||
operation is to invalidate all of the data in the newly locked byte- range. | operation is to invalidate all of the data in the newly locked byte- range. | |||
</t> | </li> | |||
<t> | <li> | |||
Second, before releasing a WRITE_LT lock for a byte-range, all modif ied data | Second, before releasing a WRITE_LT lock for a byte-range, all modif ied data | |||
for that byte-range must be flushed to the server. The modified dat a must | for that byte-range must be flushed to the server. The modified dat a must | |||
also be written to stable storage. | also be written to stable storage. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Note that flushing data to the server and the invalidation of cached | Note that flushing data to the server and the invalidation of cached | |||
data must reflect the actual byte-ranges locked or unlocked. Rounding | data must reflect the actual byte-ranges locked or unlocked. Rounding | |||
these up or down to reflect client cache block boundaries will cause | these up or down to reflect client cache block boundaries will cause | |||
problems if not carefully done. For example, writing a modified block | problems if not carefully done. For example, writing a modified block | |||
when only half of that block is within an area being unlocked may | when only half of that block is within an area being unlocked may | |||
cause invalid modification to the byte-range outside the unlocked area. | cause invalid modification to the byte-range outside the unlocked area. | |||
This, in turn, may be part of a byte-range locked by another client. | This, in turn, may be part of a byte-range locked by another client. | |||
Clients can avoid this situation by synchronously performing portions | Clients can avoid this situation by synchronously performing portions | |||
of WRITE operations that overlap that portion (initial or final) that | of WRITE operations that overlap that portion (initial or final) that | |||
is not a full block. Similarly, invalidating a locked area that is | is not a full block. Similarly, invalidating a locked area that is | |||
not an integral number of full buffer blocks would require the client | not an integral number of full buffer blocks would require the client | |||
to read one or two partial blocks from the server if the revalidation | to read one or two partial blocks from the server if the revalidation | |||
procedure shows that the data that the client possesses may not be | procedure shows that the data that the client possesses may not be | |||
valid. | valid. | |||
</t> | </t> | |||
<t> | <t> | |||
The data that is written to the server as a prerequisite to the | The data that is written to the server as a prerequisite to the | |||
unlocking of a byte-range must be written, at the server, to stable | unlocking of a byte-range must be written, at the server, to stable | |||
storage. The client may accomplish this either with synchronous | storage. The client may accomplish this either with synchronous | |||
writes or by following asynchronous writes with a COMMIT operation. | writes or by following asynchronous writes with a COMMIT operation. | |||
This is required because retransmission of the modified data after a | This is required because retransmission of the modified data after a | |||
server restart might conflict with a lock held by another client. | server restart might conflict with a lock held by another client. | |||
</t> | </t> | |||
<t> | <t> | |||
A client implementation may choose to accommodate applications that | A client implementation may choose to accommodate applications that | |||
use byte-range locking in non-standard ways (e.g., using a byte-range lo ck as a | use byte-range locking in non-standard ways (e.g., using a byte-range lo ck as a | |||
global semaphore) by flushing to the server more data upon a LOCKU | global semaphore) by flushing to the server more data upon a LOCKU | |||
than is covered by the locked range. This may include modified data | than is covered by the locked range. This may include modified data | |||
within files other than the one for which the unlocks are being done. | within files other than the one for which the unlocks are being done. | |||
In such cases, the client must not interfere with applications whose | In such cases, the client must not interfere with applications whose | |||
READs and WRITEs are being done only within the bounds of byte-range loc ks | READs and WRITEs are being done only within the bounds of byte-range loc ks | |||
that the application holds. For example, an application locks a | that the application holds. For example, an application locks a | |||
single byte of a file and proceeds to write that single byte. A | single byte of a file and proceeds to write that single byte. A | |||
client that chose to handle a LOCKU by flushing all modified data to | client that chose to handle a LOCKU by flushing all modified data to | |||
skipping to change at line 13080 ¶ | skipping to change at line 13360 ¶ | |||
unrelated LOCKU operation. However, it would not be valid to write the entire | unrelated LOCKU operation. However, it would not be valid to write the entire | |||
block in which that single written byte was located since it includes | block in which that single written byte was located since it includes | |||
an area that is not locked and might be locked by another client. | an area that is not locked and might be locked by another client. | |||
Client implementations can avoid this problem by dividing files with | Client implementations can avoid this problem by dividing files with | |||
modified data into those for which all modifications are done to areas | modified data into those for which all modifications are done to areas | |||
covered by an appropriate byte-range lock and those for which there are | covered by an appropriate byte-range lock and those for which there are | |||
modifications not covered by a byte-range lock. Any writes done for the | modifications not covered by a byte-range lock. Any writes done for the | |||
former class of files must not include areas not locked and thus not | former class of files must not include areas not locked and thus not | |||
modified on the client. | modified on the client. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Data Caching and Mandatory File Locking" > | <section numbered="true" toc="default"> | |||
<t> | <name>Data Caching and Mandatory File Locking</name> | |||
<t> | ||||
Client-side data caching needs to respect mandatory byte-range locking w hen | Client-side data caching needs to respect mandatory byte-range locking w hen | |||
it is in effect. The presence of mandatory byte-range locking for a giv en | it is in effect. The presence of mandatory byte-range locking for a giv en | |||
file is indicated when the client gets back NFS4ERR_LOCKED from a READ | file is indicated when the client gets back NFS4ERR_LOCKED from a READ | |||
or WRITE operation on a file for which it has an appropriate share reser vation. When | or WRITE operation on a file for which it has an appropriate share reser vation. When | |||
mandatory locking is in effect for a file, the client must check for | mandatory locking is in effect for a file, the client must check for | |||
an appropriate byte-range lock for data being read or written. If a byt e-range lock | an appropriate byte-range lock for data being read or written. If a byt e-range lock | |||
exists for the range being read or written, the client may satisfy the | exists for the range being read or written, the client may satisfy the | |||
request using the client's validated cache. If an appropriate | request using the client's validated cache. If an appropriate | |||
byte-range lock is not held for the range of the read or write, the read or write | byte-range lock is not held for the range of the read or write, the read or write | |||
request must not be satisfied by the client's cache and the request | request must not be satisfied by the client's cache and the request | |||
must be sent to the server for processing. When a read or write | must be sent to the server for processing. When a read or write | |||
request partially overlaps a locked byte-range, the request should be | request partially overlaps a locked byte-range, the request should be | |||
subdivided into multiple pieces with each byte-range (locked or not) | subdivided into multiple pieces with each byte-range (locked or not) | |||
treated appropriately. | treated appropriately. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="data_caching_and_file_identity" | <section anchor="data_caching_and_file_identity" numbered="true" toc="de | |||
title="Data Caching and File Identity" > | fault"> | |||
<name>Data Caching and File Identity</name> | ||||
<t> | <t> | |||
When clients cache data, the file data needs to be organized according | When clients cache data, the file data needs to be organized according | |||
to the file system object to which the data belongs. For NFSv3 | to the file system object to which the data belongs. For NFSv3 | |||
clients, the typical practice has been to assume for the purpose of | clients, the typical practice has been to assume for the purpose of | |||
caching that distinct filehandles represent distinct file system | caching that distinct filehandles represent distinct file system | |||
objects. The client then has the choice to organize and maintain the | objects. The client then has the choice to organize and maintain the | |||
data cache on this basis. | data cache on this basis. | |||
</t> | </t> | |||
<t> | <t> | |||
In the NFSv4.1 protocol, there is now the possibility to have | In the NFSv4.1 protocol, there is now the possibility to have | |||
significant deviations from a "one filehandle per object" model | significant deviations from a "one filehandle per object" model | |||
because a filehandle may be constructed on the basis of the object's | because a filehandle may be constructed on the basis of the object's | |||
pathname. Therefore, clients need a reliable method to determine if | pathname. Therefore, clients need a reliable method to determine if | |||
two filehandles designate the same file system object. If clients | two filehandles designate the same file system object. If clients | |||
were simply to assume that all distinct filehandles denote distinct | were simply to assume that all distinct filehandles denote distinct | |||
objects and proceed to do data caching on this basis, caching | objects and proceed to do data caching on this basis, caching | |||
inconsistencies would arise between the distinct client-side objects | inconsistencies would arise between the distinct client-side objects | |||
that mapped to the same server-side object. | that mapped to the same server-side object. | |||
</t> | </t> | |||
<t> | <t> | |||
By providing a method to differentiate filehandles, the NFSv4.1 | By providing a method to differentiate filehandles, the NFSv4.1 | |||
protocol alleviates a potential functional regression in comparison | protocol alleviates a potential functional regression in comparison | |||
with the NFSv3 protocol. Without this method, caching | with the NFSv3 protocol. Without this method, caching | |||
inconsistencies within the same client could occur, and this has not | inconsistencies within the same client could occur, and this has not | |||
been present in previous versions of the NFS protocol. Note that it | been present in previous versions of the NFS protocol. Note that it | |||
is possible to have such inconsistencies with applications executing | is possible to have such inconsistencies with applications executing | |||
on multiple clients, but that is not the issue being addressed here. | on multiple clients, but that is not the issue being addressed here. | |||
</t> | </t> | |||
<t> | <t> | |||
For the purposes of data caching, the following steps allow an | For the purposes of data caching, the following steps allow an | |||
NFSv4.1 client to determine whether two distinct filehandles denote | NFSv4.1 client to determine whether two distinct filehandles denote | |||
the same server-side object: | the same server-side object: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If GETATTR directed to two filehandles returns different values of t he | If GETATTR directed to two filehandles returns different values of t he | |||
fsid attribute, then the filehandles represent distinct objects. | fsid attribute, then the filehandles represent distinct objects. | |||
</t> | </li> | |||
<t> | <li> | |||
If GETATTR for any file with an fsid that matches the fsid of the tw o | If GETATTR for any file with an fsid that matches the fsid of the tw o | |||
filehandles in question returns a unique_handles attribute with a | filehandles in question returns a unique_handles attribute with a | |||
value of TRUE, then the two objects are distinct. | value of TRUE, then the two objects are distinct. | |||
</t> | </li> | |||
<t> | <li> | |||
If GETATTR directed to the two filehandles does not return the filei d | If GETATTR directed to the two filehandles does not return the filei d | |||
attribute for both of the handles, then it cannot be determined | attribute for both of the handles, then it cannot be determined | |||
whether the two objects are the same. Therefore, | whether the two objects are the same. Therefore, | |||
operations that depend on that knowledge (e.g., | operations that depend on that knowledge (e.g., | |||
client-side data caching) cannot be | client-side data caching) cannot be | |||
done reliably. Note that if GETATTR does not return the fileid | done reliably. Note that if GETATTR does not return the fileid | |||
attribute for both filehandles, it will return it for neither of | attribute for both filehandles, it will return it for neither of | |||
the filehandles, since the fsid for both filehandles is the same. | the filehandles, since the fsid for both filehandles is the same. | |||
</t> | </li> | |||
<t> | <li> | |||
If GETATTR directed to the two filehandles returns different values | If GETATTR directed to the two filehandles returns different values | |||
for the fileid attribute, then they are distinct objects. | for the fileid attribute, then they are distinct objects. | |||
</t> | </li> | |||
<t> | <li> | |||
Otherwise, they are the same object. | Otherwise, they are the same object. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="open_delegation" numbered="true" toc="default"> | |||
<section title="Open Delegation" anchor="open_delegation" > | <name>Open Delegation</name> | |||
<t> | <t> | |||
When a file is being OPENed, the server may delegate further handling | When a file is being OPENed, the server may delegate further handling | |||
of opens and closes for that file to the opening client. Any such | of opens and closes for that file to the opening client. Any such | |||
delegation is recallable since the circumstances that allowed for the | delegation is recallable since the circumstances that allowed for the | |||
delegation are subject to change. In particular, if the server | delegation are subject to change. In particular, if the server | |||
receives a conflicting OPEN from another client, the server must recall | receives a conflicting OPEN from another client, the server must recall | |||
the delegation before deciding whether the OPEN from the other client | the delegation before deciding whether the OPEN from the other client | |||
may be granted. Making a delegation is up to the server, and clients | may be granted. Making a delegation is up to the server, and clients | |||
should not assume that any particular OPEN either will or will not | should not assume that any particular OPEN either will or will not | |||
result in an OPEN delegation. The following is a typical set of | result in an OPEN delegation. The following is a typical set of | |||
conditions that servers might use in deciding whether an OPEN should be | conditions that servers might use in deciding whether an OPEN should be | |||
delegated: | delegated: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The client must be able to respond to the | The client must be able to respond to the | |||
server's callback requests. If a backchannel | server's callback requests. If a backchannel | |||
has been established, the server will send | has been established, the server will send | |||
a CB_COMPOUND request, containing a single | a CB_COMPOUND request, containing a single | |||
operation, CB_SEQUENCE, for a test of backchannel | operation, CB_SEQUENCE, for a test of backchannel | |||
availability. | availability. | |||
</t> | </li> | |||
<t> | <li> | |||
The client must have responded properly to previous recalls. | The client must have responded properly to previous recalls. | |||
</t> | </li> | |||
<t> | <li> | |||
There must be no current OPEN conflicting with the requested | There must be no current OPEN conflicting with the requested | |||
delegation. | delegation. | |||
</t> | </li> | |||
<t> | <li> | |||
There should be no current delegation that conflicts with the | There should be no current delegation that conflicts with the | |||
delegation being requested. | delegation being requested. | |||
</t> | </li> | |||
<t> | <li> | |||
The probability of future conflicting open requests should be | The probability of future conflicting open requests should be | |||
low based on the recent history of the file. | low based on the recent history of the file. | |||
</t> | </li> | |||
<t> | <li> | |||
The existence of any server-specific semantics of OPEN/CLOSE | The existence of any server-specific semantics of OPEN/CLOSE | |||
that would make the required handling incompatible with the | that would make the required handling incompatible with the | |||
prescribed handling that the delegated client would apply | prescribed handling that the delegated client would apply | |||
(see below). | (see below). | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
There are two types of OPEN delegations: OPEN_DELEGATE_READ and OPEN_DELEG ATE_WRITE. An OPEN_DELEGATE_READ | There are two types of OPEN delegations: OPEN_DELEGATE_READ and OPEN_DELEG ATE_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 no t | OPEN_DELEGATE_READ delegations may be outstanding simultaneously and do no t | |||
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 g iven | |||
file at a given time, and it is inconsistent with any OPEN_DELEGATE_READ d elegations. | file at a given time, and it is inconsistent with any OPEN_DELEGATE_READ d elegations. | |||
</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 dele gation | accessing the file's data. The client holding an OPEN_DELEGATE_WRITE dele gation | |||
may only locally affect file attributes that are intimately | may only locally affect file attributes that are intimately | |||
connected with the file data: size, change, time_access, | connected with the file data: size, change, time_access, | |||
time_metadata, and time_modify. | time_metadata, and time_modify. | |||
All other attributes must be reflected on the server. | All other attributes must be reflected on the server. | |||
</t> | </t> | |||
<t> | <t> | |||
When a client has an OPEN delegation, it does not need to send OPENs or | When a client has an OPEN delegation, it does not need to send OPENs or | |||
CLOSEs to the server. Instead, the client may update the | CLOSEs to the server. Instead, the client may update the | |||
appropriate status internally. For an OPEN_DELEGATE_READ delegation, opens | appropriate status internally. For an OPEN_DELEGATE_READ delegation, opens | |||
that cannot be handled locally (opens that are for OPEN4_SHARE_ACCESS_WRIT E/OPEN4_SHARE_ACCESS_BOTH or that | that cannot be handled locally (opens that are for OPEN4_SHARE_ACCESS_WRIT E/OPEN4_SHARE_ACCESS_BOTH or that | |||
deny OPEN4_SHARE_ACCESS_READ access) must be sent to the server. | deny OPEN4_SHARE_ACCESS_READ access) must be sent to the server. | |||
</t> | </t> | |||
<t> | <t> | |||
When an OPEN delegation is made, the reply to the OPEN contains an | When an OPEN delegation is made, the reply to the OPEN contains an | |||
OPEN delegation structure that specifies the following: | OPEN delegation structure that specifies the following: | |||
<list style="symbols"> | ||||
<t> | ||||
the type of delegation (OPEN_DELEGATE_READ or OPEN_DELEGATE_WRITE). | ||||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
the type of delegation (OPEN_DELEGATE_READ or OPEN_DELEGATE_WRITE). | ||||
</li> | ||||
<li> | ||||
space limitation information to control flushing of data on close | space limitation information to control flushing of data on close | |||
(OPEN_DELEGATE_WRITE delegation only; | (OPEN_DELEGATE_WRITE delegation only; | |||
see <xref target="open_delegation_caching" />) | see <xref target="open_delegation_caching" format="default"/>) | |||
</t> | </li> | |||
<t> | <li> | |||
an nfsace4 specifying read and write permissions | an nfsace4 specifying read and write permissions | |||
</t> | </li> | |||
<t> | <li> | |||
a stateid to represent the delegation | a stateid to represent the delegation | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
The delegation stateid is separate and distinct from the stateid for | The delegation stateid is separate and distinct from the stateid for | |||
the OPEN proper. The standard stateid, unlike the delegation stateid, | the OPEN proper. The standard stateid, unlike the delegation stateid, | |||
is associated with a particular lock-owner and will continue to be | is associated with a particular lock-owner and will continue to be | |||
valid after the delegation is recalled and the file remains open. | valid after the delegation is recalled and the file remains open. | |||
</t> | </t> | |||
<t> | <t> | |||
When a request internal to the client is made to open a file and an OPEN | When a request internal to the client is made to open a file and an OPEN | |||
delegation is in effect, it will be accepted or rejected solely on the | delegation is in effect, it will be accepted or rejected solely on the | |||
basis of the following conditions. Any requirement for other checks | basis of the following conditions. Any requirement for other checks | |||
to be made by the delegate should result in the OPEN delegation being | to be made by the delegate should result in the OPEN delegation being | |||
denied so that the checks can be made by the server itself. | denied so that the checks can be made by the server itself. | |||
<list style="symbols"> | ||||
<t> | ||||
The access and deny bits for the request and the file as | ||||
described in <xref target="share_reserve" />. | ||||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The access and deny bits for the request and the file as | ||||
described in <xref target="share_reserve" format="default"/>. | ||||
</li> | ||||
<li> | ||||
The read and write permissions as determined below. | The read and write permissions as determined below. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
The nfsace4 passed with delegation can be used to avoid frequent | The nfsace4 passed with delegation can be used to avoid frequent | |||
ACCESS calls. The permission check should be as follows: | ACCESS calls. The permission check should be as follows: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If the nfsace4 indicates that the open may be done, then it should be | If the nfsace4 indicates that the open may be done, then it should be | |||
granted without reference to the server. | granted without reference to the server. | |||
</t> | </li> | |||
<t> | <li> | |||
If the nfsace4 indicates that the open may not be done, then an ACCESS | If the nfsace4 indicates that the open may not be done, then an ACCESS | |||
request must be sent to the server to obtain the definitive answer. | request must be sent to the server to obtain the definitive answer. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
The server may return an nfsace4 that is more restrictive than the | The server may return an nfsace4 that is more restrictive than the | |||
actual ACL of the file. This includes an nfsace4 that specifies | actual ACL of the file. This includes an nfsace4 that specifies | |||
denial of all access. Note that some common practices such as mapping | denial of all access. Note that some common practices such as mapping | |||
the traditional user "root" to the user "nobody" (see <xref target="owner_ owner_group"/>) may make it incorrect | the traditional user "root" to the user "nobody" (see <xref target="owner_ owner_group" format="default"/>) may make it incorrect | |||
to return the actual ACL of the file in the delegation response. | to return the actual ACL of the file in the delegation response. | |||
</t> | </t> | |||
<t> | <t> | |||
The use of a delegation together with various other forms of caching | The use of a delegation together with various other forms of caching | |||
creates the possibility that no server authentication and authorization | creates the possibility that no server authentication and authorization | |||
will ever be | will ever be | |||
performed for a given user since all of the user's requests might be | performed for a given user since all of the user's requests might be | |||
satisfied locally. Where the client is depending on the server for | satisfied locally. Where the client is depending on the server for | |||
authentication and authorization, the client should be sure authentication and authorization occurs for | authentication and authorization, the client should be sure authentication and authorization occurs for | |||
each user by use of the ACCESS operation. This should be the case | each user by use of the ACCESS operation. This should be the case | |||
even if an ACCESS operation would not be required otherwise. As | even if an ACCESS operation would not be required otherwise. As | |||
mentioned before, the server may enforce frequent authentication by | mentioned before, the server may enforce frequent authentication by | |||
returning an nfsace4 denying all access with every OPEN delegation. | returning an nfsace4 denying all access with every OPEN delegation. | |||
</t> | </t> | |||
<section title="Open Delegation and Data Caching" | <section anchor="open_delegation_caching" numbered="true" toc="default"> | |||
anchor="open_delegation_caching" > | <name>Open Delegation and Data Caching</name> | |||
<t> | <t> | |||
An OPEN delegation allows much of the message overhead associated with | An OPEN delegation allows much of the message overhead associated with | |||
the opening and closing files to be eliminated. An open when an OPEN | the opening and closing files to be eliminated. An open when an OPEN | |||
delegation is in effect does not require that a validation | delegation is in effect does not require that a validation | |||
message be sent to the server. The continued endurance of the | message be sent to the server. The continued endurance of the | |||
"OPEN_DELEGATE_READ delegation" provides a guarantee that no OPEN | "OPEN_DELEGATE_READ delegation" provides a guarantee that no OPEN | |||
for OPEN4_SHARE_ACCESS_WRITE/OPEN4_SHARE_ACCESS_BOTH, and thus | for OPEN4_SHARE_ACCESS_WRITE/OPEN4_SHARE_ACCESS_BOTH, and thus | |||
no write, has occurred. Similarly, when closing a file opened | no write, has occurred. Similarly, when closing a file opened | |||
for OPEN4_SHARE_ACCESS_WRITE/OPEN4_SHARE_ACCESS_BOTH and if an OPEN_DELE GATE_WRITE delegation is in effect, | for OPEN4_SHARE_ACCESS_WRITE/OPEN4_SHARE_ACCESS_BOTH and if an OPEN_DELE GATE_WRITE delegation is in effect, | |||
the data written does not have to be written to the server until | the data written does not have to be written to the server until | |||
the OPEN delegation is recalled. The continued endurance of | the OPEN delegation is recalled. The continued endurance of | |||
the OPEN delegation provides a | the OPEN delegation provides a | |||
guarantee that no open, and thus no READ or WRITE, has been done by | guarantee that no open, and thus no READ or WRITE, has been done by | |||
another client. | another client. | |||
</t> | </t> | |||
<t> | <t> | |||
For the purposes of OPEN delegation, READs and WRITEs done without an | For the purposes of OPEN delegation, READs and WRITEs done without an | |||
OPEN are treated as the functional equivalents of a corresponding type | OPEN are treated as the functional equivalents of a corresponding type | |||
of OPEN. Although a client SHOULD NOT use special stateids when | of OPEN. Although a client <bcp14>SHOULD NOT</bcp14> use special statei ds when | |||
an open exists, delegation handling on the server can use the | an open exists, delegation handling on the server can use the | |||
client ID associated with the current session to determine if the | client ID associated with the current session to determine if the | |||
operation has been done by the holder of the delegation (in which | operation has been done by the holder of the delegation (in which | |||
case, no recall is necessary) or by another client (in which case, | case, no recall is necessary) or by another client (in which case, | |||
the delegation must be recalled and I/O not proceed until the | the delegation must be recalled and I/O not proceed until the | |||
delegation is returned or revoked). | delegation is returned or revoked). | |||
</t> | </t> | |||
<t> | <t> | |||
With delegations, a client is able to avoid writing data to the server | With delegations, a client is able to avoid writing data to the server | |||
when the CLOSE of a file is serviced. The file close system call is | when the CLOSE of a file is serviced. The file close system call is | |||
the usual point at which the client is notified of a lack of stable | the usual point at which the client is notified of a lack of stable | |||
storage for the modified file data generated by the application. At | storage for the modified file data generated by the application. At | |||
the close, file data is written to the server and, through normal | the close, file data is written to the server and, through normal | |||
accounting, the server is able to determine if the available file system | accounting, the server is able to determine if the available file system | |||
space for the data has been exceeded (i.e., the server returns | space for the data has been exceeded (i.e., the server returns | |||
NFS4ERR_NOSPC or NFS4ERR_DQUOT). This accounting includes quotas. | NFS4ERR_NOSPC or NFS4ERR_DQUOT). This accounting includes quotas. | |||
The introduction of delegations requires that an alternative method be | The introduction of delegations requires that an alternative method be | |||
in place for the same type of communication to occur between client | in place for the same type of communication to occur between client | |||
and server. | and server. | |||
</t> | </t> | |||
<t> | <t> | |||
In the delegation response, the server provides either the limit of | In the delegation response, the server provides either the limit of | |||
the size of the file or the number of modified blocks and associated | the size of the file or the number of modified blocks and associated | |||
block size. The server must ensure that the client will be able to | block size. The server must ensure that the client will be able to | |||
write modified data to the server of a size equal to that provided in th e | write modified data to the server of a size equal to that provided in th e | |||
original delegation. The server must make this assurance for all | original delegation. The server must make this assurance for all | |||
outstanding delegations. Therefore, the server must be careful in its | outstanding delegations. Therefore, the server must be careful in its | |||
management of available space for new or modified data, taking into | management of available space for new or modified data, taking into | |||
account available file system space and any applicable quotas. The | account available file system space and any applicable quotas. The | |||
server can recall delegations as a result of managing the available | server can recall delegations as a result of managing the available | |||
file system space. The client should abide by the server's state | file system space. The client should abide by the server's state | |||
space limits for delegations. If the client exceeds the stated limits | space limits for delegations. If the client exceeds the stated limits | |||
for the delegation, the server's behavior is undefined. | for the delegation, the server's behavior is undefined. | |||
</t> | </t> | |||
<t> | <t> | |||
Based on server conditions, quotas, or available file system space, the | Based on server conditions, quotas, or available file system space, the | |||
server may grant OPEN_DELEGATE_WRITE delegations with very restrictive s pace | server may grant OPEN_DELEGATE_WRITE delegations with very restrictive s pace | |||
limitations. The limitations may be defined in a way that will always | limitations. The limitations may be defined in a way that will always | |||
force modified data to be flushed to the server on close. | force modified data to be flushed to the server on close. | |||
</t> | </t> | |||
<t> | <t> | |||
With respect to authentication, flushing modified data to the server | With respect to authentication, flushing modified data to the server | |||
after a CLOSE has occurred may be problematic. For example, the user | after a CLOSE has occurred may be problematic. For example, the user | |||
of the application may have logged off the client, and unexpired | of the application may have logged off the client, and unexpired | |||
authentication credentials may not be present. In this case, the | authentication credentials may not be present. In this case, the | |||
client may need to take special care to ensure that local unexpired | client may need to take special care to ensure that local unexpired | |||
credentials will in fact be available. This may be accomplished by | credentials will in fact be available. This may be accomplished by | |||
tracking the expiration time of credentials and flushing data well in | tracking the expiration time of credentials and flushing data well in | |||
advance of their expiration or by making private copies of credentials | advance of their expiration or by making private copies of credentials | |||
to assure their availability when needed. | to assure their availability when needed. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Open Delegation and File Locks" > | <section numbered="true" toc="default"> | |||
<t> | <name>Open Delegation and File Locks</name> | |||
<t> | ||||
When a client holds an OPEN_DELEGATE_WRITE delegation, lock operations a re | When a client holds an OPEN_DELEGATE_WRITE delegation, lock operations a re | |||
performed locally. This includes those required for mandatory byte-rang e | performed locally. This includes those required for mandatory byte-rang e | |||
locking. This can be done since the delegation implies that there can | locking. This can be done since the delegation implies that there can | |||
be no conflicting locks. Similarly, all of the revalidations that | be no conflicting locks. Similarly, all of the revalidations that | |||
would normally be associated with obtaining locks and the flushing of | would normally be associated with obtaining locks and the flushing of | |||
data associated with the releasing of locks need not be done. | data associated with the releasing of locks need not be done. | |||
</t> | </t> | |||
<t> | <t> | |||
When a client holds an OPEN_DELEGATE_READ delegation, lock operations ar e not | When a client holds an OPEN_DELEGATE_READ delegation, lock operations ar e not | |||
performed locally. All lock operations, including those requesting | performed locally. All lock operations, including those requesting | |||
non-exclusive locks, are sent to the server for resolution. | non-exclusive locks, are sent to the server for resolution. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="handling_cb_getattr" title="Handling of CB_GETATTR" > | <section anchor="handling_cb_getattr" numbered="true" toc="default"> | |||
<t> | <name>Handling of CB_GETATTR</name> | |||
<t> | ||||
The server needs to employ special handling for a GETATTR where the | The server needs to employ special handling for a GETATTR where the | |||
target is a file that has an OPEN_DELEGATE_WRITE delegation in effect. The | target is a file that has an OPEN_DELEGATE_WRITE delegation in effect. The | |||
reason for this is that the client holding the OPEN_DELEGATE_WRITE deleg ation may | reason for this is that the client holding the OPEN_DELEGATE_WRITE deleg ation may | |||
have modified the data, and the server needs to reflect this change to | have modified the data, and the server needs to reflect this change to | |||
the second client that submitted the GETATTR. Therefore, the client | the second client that submitted the GETATTR. Therefore, the client | |||
holding the OPEN_DELEGATE_WRITE delegation needs to be interrogated. Th e server | holding the OPEN_DELEGATE_WRITE delegation needs to be interrogated. Th e server | |||
will use the CB_GETATTR operation. The only attributes that the | will use the CB_GETATTR operation. The only attributes that the | |||
server can reliably query via CB_GETATTR are size and change. | server can reliably query via CB_GETATTR are size and change. | |||
</t> | </t> | |||
<t> | <t> | |||
Since CB_GETATTR is being used to satisfy another client's GETATTR | Since CB_GETATTR is being used to satisfy another client's GETATTR | |||
request, the server only needs to know if the client holding the | request, the server only needs to know if the client holding the | |||
delegation has a modified version of the file. If the client's copy | delegation has a modified version of the file. If the client's copy | |||
of the delegated file is not modified (data or size), the server can | of the delegated file is not modified (data or size), the server can | |||
satisfy the second client's GETATTR request from the attributes stored | satisfy the second client's GETATTR request from the attributes stored | |||
locally at the server. If the file is modified, the server only needs | locally at the server. If the file is modified, the server only needs | |||
to know about this modified state. If the server determines that the | to know about this modified state. If the server determines that the | |||
file is currently modified, it will respond to the second client's | file is currently modified, it will respond to the second client's | |||
GETATTR as if the file had been modified locally at the server. | GETATTR as if the file had been modified locally at the server. | |||
</t> | </t> | |||
<t> | <t> | |||
Since the form of the change attribute is determined by the server and | Since the form of the change attribute is determined by the server and | |||
is opaque to the client, the client and server need to agree on a | is opaque to the client, the client and server need to agree on a | |||
method of communicating the modified state of the file. For the size | method of communicating the modified state of the file. For the size | |||
attribute, the client will report its current view of the file size. | attribute, the client will report its current view of the file size. | |||
For the change attribute, the handling is more involved. | For the change attribute, the handling is more involved. | |||
</t> | </t> | |||
<t> | <t> | |||
For the client, the following steps will be taken when receiving an | For the client, the following steps will be taken when receiving an | |||
OPEN_DELEGATE_WRITE delegation: | OPEN_DELEGATE_WRITE delegation: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The value of the change attribute will be obtained from the server a nd | The value of the change attribute will be obtained from the server a nd | |||
cached. Let this value be represented by c. | cached. Let this value be represented by c. | |||
</t> | </li> | |||
<t> | <li> | |||
The client will create a value greater than c that will be used for | The client will create a value greater than c that will be used for | |||
communicating that modified data is held at the client. Let this va lue be | communicating that modified data is held at the client. Let this va lue be | |||
represented by d. | represented by d. | |||
</t> | </li> | |||
<t> | <li> | |||
When the client is queried via CB_GETATTR for the change attribute, it | When the client is queried via CB_GETATTR for the change attribute, it | |||
checks to see if it holds modified data. If the file is modified, t he | checks to see if it holds modified data. If the file is modified, t he | |||
value d is returned for the change attribute value. If this file is | value d is returned for the change attribute value. If this file is | |||
not currently modified, the client returns the value c for the chang e | not currently modified, the client returns the value c for the chang e | |||
attribute. | attribute. | |||
</t> | </li> | |||
</list> | </ul> | |||
For simplicity of implementation, the client MAY for each CB_GETATTR | <t> | |||
For simplicity of implementation, the client <bcp14>MAY</bcp14> for each | ||||
CB_GETATTR | ||||
return the same value d. This is true even if, between successive | return the same value d. This is true even if, between successive | |||
CB_GETATTR operations, the client again modifies the file's data or | CB_GETATTR operations, the client again modifies the file's data or | |||
metadata in its cache. The client can return the same value because | metadata in its cache. The client can return the same value because | |||
the only requirement is that the client be able to indicate to the | the only requirement is that the client be able to indicate to the | |||
server that the client holds modified data. Therefore, the value of d | server that the client holds modified data. Therefore, the value of d | |||
may always be c + 1. | may always be c + 1. | |||
</t> | </t> | |||
<t> | <t> | |||
While the change attribute is opaque to the client in the sense that | While the change attribute is opaque to the client in the sense that | |||
it has no idea what units of time, if any, the server is counting | it has no idea what units of time, if any, the server is counting | |||
change with, it is not opaque in that the client has to treat it as an | change with, it is not opaque in that the client has to treat it as an | |||
unsigned integer, and the server has to be able to see the results of | unsigned integer, and the server has to be able to see the results of | |||
the client's changes to that integer. Therefore, the server MUST | the client's changes to that integer. Therefore, the server <bcp14>MUST </bcp14> | |||
encode the change attribute in network order when sending it to the | encode the change attribute in network order when sending it to the | |||
client. The client MUST decode it from network order to its native | client. The client <bcp14>MUST</bcp14> decode it from network order to | |||
order when receiving it, and the client MUST encode it in network order | its native | |||
order when receiving it, and the client <bcp14>MUST</bcp14> encode it in | ||||
network order | ||||
when sending it to the server. For this reason, change is defined as | when sending it to the server. For this reason, change is defined as | |||
an unsigned integer rather than an opaque array of bytes. | an unsigned integer rather than an opaque array of bytes. | |||
</t> | </t> | |||
<t> | <t> | |||
For the server, the following steps will be taken when providing an | For the server, the following steps will be taken when providing an | |||
OPEN_DELEGATE_WRITE delegation: | OPEN_DELEGATE_WRITE delegation: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Upon providing an OPEN_DELEGATE_WRITE delegation, the server will ca che a copy of the | Upon providing an OPEN_DELEGATE_WRITE delegation, the server will ca che a copy of the | |||
change attribute in the data structure it uses to record the | change attribute in the data structure it uses to record the | |||
delegation. Let this value be represented by sc. | delegation. Let this value be represented by sc. | |||
</t> | </li> | |||
<t> | <li> | |||
When a second client sends a GETATTR operation on the same file to t he | When a second client sends a GETATTR operation on the same file to t he | |||
server, the server obtains the change attribute from the first clien t. | server, the server obtains the change attribute from the first clien t. | |||
Let this value be cc. | Let this value be cc. | |||
</t> | </li> | |||
<t> | <li> | |||
If the value cc is equal to sc, the file is not modified and the | If the value cc is equal to sc, the file is not modified and the | |||
server returns the current values for change, time_metadata, and | server returns the current values for change, time_metadata, and | |||
time_modify (for example) to the second client. | time_modify (for example) to the second client. | |||
</t> | </li> | |||
<t> | <li> | |||
If the value cc is NOT equal to sc, the file is currently modified a t | If the value cc is NOT equal to sc, the file is currently modified a t | |||
the first client and most likely will be modified at the server at a | the first client and most likely will be modified at the server at a | |||
future time. The server then uses its current time to construct | future time. The server then uses its current time to construct | |||
attribute values for time_metadata and time_modify. A new value of | attribute values for time_metadata and time_modify. A new value of | |||
sc, which we will call nsc, is computed by the server, such that nsc | sc, which we will call nsc, is computed by the server, such that nsc | |||
>= sc + 1. The server then returns the constructed time_metadata, | >= sc + 1. The server then returns the constructed time_metadata , | |||
time_modify, and nsc values to the requester. The server replaces s c | time_modify, and nsc values to the requester. The server replaces s c | |||
in the delegation record with nsc. To prevent the possibility of | in the delegation record with nsc. To prevent the possibility of | |||
time_modify, time_metadata, and change from appearing to go backward | time_modify, time_metadata, and change from appearing to go backward | |||
(which would happen if the client holding the delegation fails to | (which would happen if the client holding the delegation fails to | |||
write its modified data to the server before the delegation is revok ed | write its modified data to the server before the delegation is revok ed | |||
or returned), the server SHOULD update the file's metadata record wi th | or returned), the server <bcp14>SHOULD</bcp14> update the file's met adata record with | |||
the constructed attribute values. For reasons of reasonable | the constructed attribute values. For reasons of reasonable | |||
performance, committing the constructed attribute values to stable | performance, committing the constructed attribute values to stable | |||
storage is OPTIONAL. | storage is <bcp14>OPTIONAL</bcp14>. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | As discussed earlier in this section, the client <bcp14>MAY</bcp14> retu | |||
As discussed earlier in this section, the client MAY return the same | rn the same | |||
cc value on subsequent CB_GETATTR calls, even if the file was modified | cc value on subsequent CB_GETATTR calls, even if the file was modified | |||
in the client's cache yet again between successive CB_GETATTR calls. | in the client's cache yet again between successive CB_GETATTR calls. | |||
Therefore, the server must assume that the file has been modified yet | Therefore, the server must assume that the file has been modified yet | |||
again, and MUST take care to ensure that the new nsc it constructs and | again, and <bcp14>MUST</bcp14> take care to ensure that the new nsc it c onstructs and | |||
returns is greater than the previous nsc it returned. An example | returns is greater than the previous nsc it returned. An example | |||
implementation's delegation record would satisfy this mandate by | implementation's delegation record would satisfy this mandate by | |||
including a boolean field (let us call it "modified") that is set to | including a boolean field (let us call it "modified") that is set to | |||
FALSE when the delegation is granted, and an sc value set at the time | FALSE when the delegation is granted, and an sc value set at the time | |||
of grant to the change attribute value. The modified field would be | of grant to the change attribute value. The modified field would be | |||
set to TRUE the first time cc != sc, and would stay TRUE until the | set to TRUE the first time cc != sc, and would stay TRUE until the | |||
delegation is returned or revoked. The processing for constructing | delegation is returned or revoked. The processing for constructing | |||
nsc, time_modify, and time_metadata would use this pseudo code: | nsc, time_modify, and time_metadata would use this pseudo code: | |||
<figure> | </t> | |||
<artwork> | <sourcecode type="pseudocode"><![CDATA[ | |||
if (!modified) { | if (!modified) { | |||
do CB_GETATTR for change and size; | do CB_GETATTR for change and size; | |||
if (cc != sc) | if (cc != sc) | |||
modified = TRUE; | modified = TRUE; | |||
} else { | } else { | |||
do CB_GETATTR for size; | do CB_GETATTR for size; | |||
} | } | |||
if (modified) { | if (modified) { | |||
sc = sc + 1; | sc = sc + 1; | |||
time_modify = time_metadata = current_time; | time_modify = time_metadata = current_time; | |||
update sc, time_modify, time_metadata into file's metadata; | update sc, time_modify, time_metadata into file's metadata; | |||
} | }]]></sourcecode> | |||
<t> | ||||
</artwork> | ||||
</figure> | ||||
This would return to the client (that sent GETATTR) the attributes | This would return to the client (that sent GETATTR) the attributes | |||
it requested, but make sure size comes from what | it requested, but make sure size comes from what | |||
CB_GETATTR returned. The server would not update the file's | CB_GETATTR returned. The server would not update the file's | |||
metadata with the client's modified size. | metadata with the client's modified size. | |||
</t> | </t> | |||
<t> | <t> | |||
In the case that the file attribute size is different than the | In the case that the file attribute size is different than the | |||
server's current value, the server treats this as a modification | server's current value, the server treats this as a modification | |||
regardless of the value of the change attribute retrieved via | regardless of the value of the change attribute retrieved via | |||
CB_GETATTR and responds to the second client as in the last step. | CB_GETATTR and responds to the second client as in the last step. | |||
</t> | </t> | |||
<t> | <t> | |||
This methodology resolves issues of clock differences between client | This methodology resolves issues of clock differences between client | |||
and server and other scenarios where the use of CB_GETATTR break down. | and server and other scenarios where the use of CB_GETATTR break down. | |||
</t> | </t> | |||
<t> | <t> | |||
It should be noted that the server is under no obligation to use | It should be noted that the server is under no obligation to use | |||
CB_GETATTR, and therefore the server MAY simply recall the delegation | CB_GETATTR, and therefore the server <bcp14>MAY</bcp14> simply recall th e delegation | |||
to avoid its use. | to avoid its use. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="Recall of Open Delegation" > | <name>Recall of Open Delegation</name> | |||
<t> | ||||
The following events necessitate recall of an OPEN delegation: | ||||
<list style="symbols"> | ||||
<t> | <t> | |||
The following events necessitate recall of an OPEN delegation: | ||||
</t> | ||||
<ul spacing="normal"> | ||||
<li> | ||||
potentially conflicting OPEN request (or a READ or WRITE operation | potentially conflicting OPEN request (or a READ or WRITE operation | |||
done with a special stateid) | done with a special stateid) | |||
</t> | </li> | |||
<t> | <li> | |||
SETATTR sent by another client | SETATTR sent by another client | |||
</t> | </li> | |||
<t> | <li> | |||
REMOVE request for the file | REMOVE request for the file | |||
</t> | </li> | |||
<t> | <li> | |||
RENAME request for the file as either the source or target of the RE NAME | RENAME request for the file as either the source or target of the RE NAME | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
Whether a RENAME of a directory in the path leading to the file | Whether a RENAME of a directory in the path leading to the file | |||
results in recall of an OPEN delegation depends on the semantics of | results in recall of an OPEN delegation depends on the semantics of | |||
the server's file system. If that file system denies such RENAMEs when | the server's file system. If that file system denies such RENAMEs when | |||
a file is open, the recall must be performed to determine whether the | a file is open, the recall must be performed to determine whether the | |||
file in question is, in fact, open. | file in question is, in fact, open. | |||
</t> | </t> | |||
<t> | <t> | |||
In addition to the situations above, the server may choose to recall | In addition to the situations above, the server may choose to recall | |||
OPEN delegations at any time if resource constraints make it advisable | OPEN delegations at any time if resource constraints make it advisable | |||
to do so. Clients should always be prepared for the possibility of | to do so. Clients should always be prepared for the possibility of | |||
recall. | recall. | |||
</t> | </t> | |||
<t> | <t> | |||
When a client receives a recall for an OPEN delegation, it needs | When a client receives a recall for an OPEN delegation, it needs | |||
to update state on the server before returning the delegation. | to update state on the server before returning the delegation. | |||
These same updates must be done whenever a client chooses to | These same updates must be done whenever a client chooses to | |||
return a delegation voluntarily. The following items of state | return a delegation voluntarily. The following items of state | |||
need to be dealt with: | need to be dealt with: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If the file associated with the delegation is no longer open and no | If the file associated with the delegation is no longer open and no | |||
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. | |||
</t> | </li> | |||
<t> | <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 wil l | operations must be sent to the server. The appropriate stateids wil l | |||
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" />, which describes the OPEN operation, | <xref target="OP_OPEN" format="default"/>, which describes the OPEN | |||
operation, | ||||
for details.) | for details.) | |||
</t> | </li> | |||
<t> | <li> | |||
If there are granted byte-range locks, the corresponding LOCK operat ions | If there are granted byte-range locks, the corresponding LOCK operat ions | |||
need to be performed. This applies to the OPEN_DELEGATE_WRITE deleg ation case | need to be performed. This applies to the OPEN_DELEGATE_WRITE deleg ation case | |||
only. | only. | |||
</t> | </li> | |||
<t> | <li> | |||
For an OPEN_DELEGATE_WRITE delegation, if | For an OPEN_DELEGATE_WRITE delegation, if | |||
at the time of recall the file is not open for | at the time of recall the file is not open for | |||
OPEN4_SHARE_ACCESS_WRITE/OPEN4_SHARE_ACCESS_BOTH, all modified | OPEN4_SHARE_ACCESS_WRITE/OPEN4_SHARE_ACCESS_BOTH, all modified | |||
data for the file must be flushed to the | data for the file must be flushed to the | |||
server. If the delegation had not existed, the client would have do ne | server. If the delegation had not existed, the client would have do ne | |||
this data flush before the CLOSE operation. | this data flush before the CLOSE operation. | |||
</t> | </li> | |||
<t> | <li> | |||
For an OPEN_DELEGATE_WRITE delegation when a file is still open at t he time of | For an OPEN_DELEGATE_WRITE delegation when a file is still open at t he time of | |||
recall, any modified data for the file needs to be flushed to the | recall, any modified data for the file needs to be flushed to the | |||
server. | server. | |||
</t> | </li> | |||
<t> | <li> | |||
With the OPEN_DELEGATE_WRITE delegation in place, it is possible tha t the file | With the OPEN_DELEGATE_WRITE delegation in place, it is possible tha t the file | |||
was truncated during the duration of the delegation. For example, t he | was truncated during the duration of the delegation. For example, t he | |||
truncation could have occurred as a result of an OPEN UNCHECKED with a | truncation could have occurred as a result of an OPEN UNCHECKED with a | |||
size attribute value of zero. Therefore, if a truncation of | size attribute value of zero. Therefore, if a truncation of | |||
the file has occurred and this operation has not been propagated to | the file has occurred and this operation has not been propagated to | |||
the server, the truncation must occur before any modified data is | the server, the truncation must occur before any modified data is | |||
written to the server. | written to the server. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
In the case of OPEN_DELEGATE_WRITE delegation, byte-range locking impose s some | In the case of OPEN_DELEGATE_WRITE delegation, byte-range locking impose s some | |||
additional requirements. To precisely maintain the associated | additional requirements. To precisely maintain the associated | |||
invariant, it is required to flush any modified data in any byte-range f or | invariant, it is required to flush any modified data in any byte-range f or | |||
which a WRITE_LT lock was released while the OPEN_DELEGATE_WRITE delegat ion was in | which a WRITE_LT lock was released while the OPEN_DELEGATE_WRITE delegat ion was in | |||
effect. However, because the OPEN_DELEGATE_WRITE delegation implies no other | effect. However, because the OPEN_DELEGATE_WRITE delegation implies no other | |||
locking by other clients, a simpler implementation is to flush all | locking by other clients, a simpler implementation is to flush all | |||
modified data for the file (as described just above) if any WRITE_LT loc k | modified data for the file (as described just above) if any WRITE_LT loc k | |||
has been released while the OPEN_DELEGATE_WRITE delegation was in effect . | has been released while the OPEN_DELEGATE_WRITE delegation was in effect . | |||
</t> | </t> | |||
<t> | <t> | |||
An implementation need not wait until delegation recall (or | An implementation need not wait until delegation recall (or | |||
the decision to voluntarily return a delegation) to perform any of the a bove | the decision to voluntarily return a delegation) to perform any of the a bove | |||
actions, if implementation considerations (e.g., resource availability | actions, if implementation considerations (e.g., resource availability | |||
constraints) make that desirable. Generally, however, the fact that | constraints) make that desirable. Generally, however, the fact that | |||
the actual OPEN state of the file may continue to change makes it not | the actual OPEN state of the file may continue to change makes it not | |||
worthwhile to send information about opens and closes to the server, | worthwhile to send information about opens and closes to the server, | |||
except as part of delegation return. An exception is | except as part of delegation return. An exception is | |||
when the client has no more internal opens of the file. In this | when the client has no more internal opens of the file. In this | |||
case, sending a CLOSE is useful because it | case, sending a CLOSE is useful because it | |||
reduces resource utilization on the client | reduces resource utilization on the client | |||
and server. | and server. | |||
Regardless of the client's choices on scheduling these | Regardless of the client's choices on scheduling these | |||
actions, all must be performed before the delegation is returned, | actions, all must be performed before the delegation is returned, | |||
including (when applicable) the close that corresponds to the OPEN | including (when applicable) the close that corresponds to the OPEN | |||
that resulted in the delegation. These actions can be performed | that resulted in the delegation. These actions can be performed | |||
either in previous requests or in previous operations in the same | either in previous requests or in previous operations in the same | |||
COMPOUND request. | COMPOUND request. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Clients That Fail to Honor Delegation Recalls" > | <section numbered="true" toc="default"> | |||
<t> | <name>Clients That Fail to Honor Delegation Recalls</name> | |||
<t> | ||||
A client may fail to respond to a recall for various reasons, such as | A client may fail to respond to a recall for various reasons, such as | |||
a failure of the backchannel from server to the client. The client | a failure of the backchannel from server to the client. The client | |||
may be unaware of a failure in the backchannel. This lack of | may be unaware of a failure in the backchannel. This lack of | |||
awareness could result in the client finding out long after the | awareness could result in the client finding out long after the | |||
failure that its delegation has been revoked, and another client has | failure that its delegation has been revoked, and another client has | |||
modified the data for which the client had a delegation. This is | modified the data for which the client had a delegation. This is | |||
especially a problem for the client that held an OPEN_DELEGATE_WRITE del egation. | especially a problem for the client that held an OPEN_DELEGATE_WRITE del egation. | |||
</t> | </t> | |||
<t> | <t> | |||
Status bits returned by SEQUENCE operations help to provide an | Status bits returned by SEQUENCE operations help to provide an | |||
alternate way of informing the client of issues regarding the | alternate way of informing the client of issues regarding the | |||
status of the backchannel and of recalled delegations. When the | status of the backchannel and of recalled delegations. When the | |||
backchannel is not available, the server returns the status bit | backchannel is not available, the server returns the status bit | |||
SEQ4_STATUS_CB_PATH_DOWN on SEQUENCE operations. The client can | SEQ4_STATUS_CB_PATH_DOWN on SEQUENCE operations. The client can | |||
react by attempting to re-establish the backchannel and by | react by attempting to re-establish the backchannel and by | |||
returning recallable objects if a backchannel cannot be successfully | returning recallable objects if a backchannel cannot be successfully | |||
re-established. | re-established. | |||
</t> | </t> | |||
<t> | <t> | |||
Whether the backchannel is functioning or not, it may be that the | Whether the backchannel is functioning or not, it may be that the | |||
recalled delegation is not returned. Note that the client's lease | recalled delegation is not returned. Note that the client's lease | |||
might still be renewed, even though the recalled delegation is not | might still be renewed, even though the recalled delegation is not | |||
returned. In this situation, servers SHOULD revoke delegations that | returned. In this situation, servers <bcp14>SHOULD</bcp14> revoke deleg ations that | |||
are not returned in a period of time equal to the lease period. This | are not returned in a period of time equal to the lease period. This | |||
period of time should allow the client time to note the | period of time should allow the client time to note the | |||
backchannel-down status and re-establish the backchannel. | backchannel-down status and re-establish the backchannel. | |||
</t> | </t> | |||
<t> | <t> | |||
When delegations are revoked, the server will return with the | When delegations are revoked, the server will return with the | |||
SEQ4_STATUS_RECALLABLE_STATE_REVOKED status bit set on subsequent | SEQ4_STATUS_RECALLABLE_STATE_REVOKED status bit set on subsequent | |||
SEQUENCE operations. The client should note this and then use | SEQUENCE operations. The client should note this and then use | |||
TEST_STATEID to find which delegations have been revoked. | TEST_STATEID to find which delegations have been revoked. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Delegation Revocation" > | <section numbered="true" toc="default"> | |||
<t> | <name>Delegation Revocation</name> | |||
<t> | ||||
At the point a delegation is revoked, if there are associated opens | At the point a delegation is revoked, if there are associated opens | |||
on the client, these opens may or may not be revoked. If no | on the client, these opens may or may not be revoked. If no | |||
byte-range lock or open is granted that is inconsistent with the existin g open, | byte-range lock or open is granted that is inconsistent with the existin g open, | |||
the stateid for the open may remain valid and be disconnected | the stateid for the open may remain valid and be disconnected | |||
from the revoked delegation, just as would be the case if the | from the revoked delegation, just as would be the case if the | |||
delegation were returned. | delegation were returned. | |||
</t> | </t> | |||
<t> | <t> | |||
For example, if an OPEN for OPEN4_SHARE_ACCESS_BOTH with a deny of OPEN4 _SHARE_DENY_NONE is | For example, if an OPEN for OPEN4_SHARE_ACCESS_BOTH with a deny of OPEN4 _SHARE_DENY_NONE is | |||
associated with the delegation, granting of another such OPEN | associated with the delegation, granting of another such OPEN | |||
to a different client will revoke the delegation but need not | to a different client will revoke the delegation but need not | |||
revoke the OPEN, since the two OPENs are consistent with each other. | revoke the OPEN, since the two OPENs are consistent with each other. | |||
On the other hand, if an OPEN denying write access is | On the other hand, if an OPEN denying write access is | |||
granted, then the existing OPEN must be revoked. | granted, then the existing OPEN must be revoked. | |||
</t> | </t> | |||
<t> | <t> | |||
When opens and/or locks are revoked, | When opens and/or locks are revoked, | |||
the applications holding these opens or locks need to be notified. | the applications holding these opens or locks need to be notified. | |||
This notification usually occurs by returning errors for READ/WRITE | This notification usually occurs by returning errors for READ/WRITE | |||
operations or when a close is attempted for the open file. | operations or when a close is attempted for the open file. | |||
</t> | </t> | |||
<t> | <t> | |||
If no opens exist for the file at the point the delegation is revoked, | If no opens exist for the file at the point the delegation is revoked, | |||
then notification of the revocation is unnecessary. However, if there | then notification of the revocation is unnecessary. However, if there | |||
is modified data present at the client for the file, the user of the | is modified data present at the client for the file, the user of the | |||
application should be notified. Unfortunately, it may not be possible | application should be notified. Unfortunately, it may not be possible | |||
to notify the user since active applications may not be present at the | to notify the user since active applications may not be present at the | |||
client. See <xref target="revocation_recovery_write" /> | client. See <xref target="revocation_recovery_write" format="default"/> | |||
for additional details. | for additional details. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Delegations via WANT_DELEGATION" | <section anchor="via_want_delegation" numbered="true" toc="default"> | |||
anchor="via_want_delegation" > | <name>Delegations via WANT_DELEGATION</name> | |||
<t> | <t> | |||
In addition to providing delegations as part of the reply | In addition to providing delegations as part of the reply | |||
to OPEN operations, servers MAY provide delegations | to OPEN operations, servers <bcp14>MAY</bcp14> provide delegations | |||
separate from open, via the OPTIONAL WANT_DELEGATION operation. This | separate from open, via the <bcp14>OPTIONAL</bcp14> WANT_DELEGATION oper | |||
ation. This | ||||
allows delegations to be obtained in advance of an OPEN that | allows delegations to be obtained in advance of an OPEN that | |||
might benefit from them, for objects that are not a valid target | might benefit from them, for objects that are not a valid target | |||
of OPEN, or to deal with cases in which a | of OPEN, or to deal with cases in which a | |||
delegation has been recalled and the client wants to make | delegation has been recalled and the client wants to make | |||
an attempt to re-establish it if the absence of use by other | an attempt to re-establish it if the absence of use by other | |||
clients allows that. | clients allows that. | |||
</t> | </t> | |||
<t> | <t> | |||
The WANT_DELEGATION operation may be performed on any type of | The WANT_DELEGATION operation may be performed on any type of | |||
file object other than a directory. | file object other than a directory. | |||
</t> | </t> | |||
<t> | <t> | |||
When a delegation is obtained using WANT_DELEGATION, any open | When a delegation is obtained using WANT_DELEGATION, any open | |||
files for the same filehandle held by that client are to be | files for the same filehandle held by that client are to be | |||
treated as subordinate to the delegation, just as if they had | treated as subordinate to the delegation, just as if they had | |||
been created using an OPEN of type CLAIM_DELEGATE_CUR. They are | been created using an OPEN of type CLAIM_DELEGATE_CUR. They are | |||
otherwise unchanged as to seqid, access and deny modes, and the | otherwise unchanged as to seqid, access and deny modes, and the | |||
relationship with byte-range locks. Similarly, because | relationship with byte-range locks. Similarly, because | |||
existing byte-range | existing byte-range | |||
locks are subordinate to an open, those byte-range locks also become | locks are subordinate to an open, those byte-range locks also become | |||
indirectly subordinate to that new delegation. | indirectly subordinate to that new delegation. | |||
</t> | </t> | |||
<t> | <t> | |||
The WANT_DELEGATION operation provides for delivery of delegations | The WANT_DELEGATION operation provides for delivery of delegations | |||
via callbacks, when the delegations are not immediately available. | via callbacks, when the delegations are not immediately available. | |||
When a requested delegation is available, it is delivered to the | When a requested delegation is available, it is delivered to the | |||
client via a CB_PUSH_DELEG operation. When this happens, open files | client via a CB_PUSH_DELEG operation. When this happens, open files | |||
for the same filehandle become subordinate to the new delegation | for the same filehandle become subordinate to the new delegation | |||
at the point at which the delegation is delivered, just as if they had | at the point at which the delegation is delivered, just as if they had | |||
been created using an OPEN of type CLAIM_DELEGATE_CUR. | been created using an OPEN of type CLAIM_DELEGATE_CUR. | |||
Similarly, this occurs for existing byte-range locks subordinate to an o pen. | Similarly, this occurs for existing byte-range locks subordinate to an o pen. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section title="Data Caching and Revocation" anchor="data_caching_revocation" | <section anchor="data_caching_revocation" numbered="true" toc="default"> | |||
> | <name>Data Caching and Revocation</name> | |||
<t> | <t> | |||
When locks and delegations are revoked, the assumptions upon which | When locks and delegations are revoked, the assumptions upon which | |||
successful caching depends are no longer guaranteed. For any locks or | successful caching depends are no longer guaranteed. For any locks or | |||
share reservations that have been revoked, the corresponding state-owner | share reservations that have been revoked, the corresponding state-owner | |||
needs to be notified. This notification includes applications with a | needs to be notified. This notification includes applications with a | |||
file open that has a corresponding delegation that has been revoked. | file open that has a corresponding delegation that has been revoked. | |||
Cached data associated with the revocation must be removed from the | Cached data associated with the revocation must be removed from the | |||
client. In the case of modified data existing in the client's cache, | client. In the case of modified data existing in the client's cache, | |||
that data must be removed from the client without being written to | that data must be removed from the client without being written to | |||
the server. As mentioned, the assumptions made by the client are no | the server. As mentioned, the assumptions made by the client are no | |||
longer valid at the point when a lock or delegation has been revoked. | longer valid at the point when a lock or delegation has been revoked. | |||
For example, another client may have been granted a conflicting byte-range lock | For example, another client may have been granted a conflicting byte-range lock | |||
after the revocation of the byte-range lock at the first client. Therefor e, the | after the revocation of the byte-range lock at the first client. Therefor e, the | |||
data within the lock range may have been modified by the other client. | data within the lock range may have been modified by the other client. | |||
Obviously, the first client is unable to guarantee to the application | Obviously, the first client is unable to guarantee to the application | |||
what has occurred to the file in the case of revocation. | what has occurred to the file in the case of revocation. | |||
</t> | </t> | |||
<t> | <t> | |||
Notification to a state-owner will in many cases consist of simply | Notification to a state-owner will in many cases consist of simply | |||
returning an error on the next and all subsequent READs/WRITEs to the | returning an error on the next and all subsequent READs/WRITEs to the | |||
open file or on the close. Where the methods available to a client | open file or on the close. Where the methods available to a client | |||
make such notification impossible because errors for certain | make such notification impossible because errors for certain | |||
operations may not be returned, more drastic action such as signals or | operations may not be returned, more drastic action such as signals or | |||
process termination may be appropriate. The justification here is | process termination may be appropriate. The justification here is | |||
that an invariant on which an application depends may be violated. | that an invariant on which an application depends may be violated. | |||
Depending on how errors are typically treated for the client-operating | Depending on how errors are typically treated for the client-operating | |||
environment, further levels of notification including logging, console | environment, further levels of notification including logging, console | |||
messages, and GUI pop-ups may be appropriate. | messages, and GUI pop-ups may be appropriate. | |||
</t> | </t> | |||
<section title="Revocation Recovery for Write Open Delegation" | <section anchor="revocation_recovery_write" numbered="true" toc="default | |||
anchor="revocation_recovery_write" > | "> | |||
<t> | <name>Revocation Recovery for Write Open Delegation</name> | |||
<t> | ||||
Revocation recovery for an OPEN_DELEGATE_WRITE delegation poses the spec ial | Revocation recovery for an OPEN_DELEGATE_WRITE delegation poses the spec ial | |||
issue of modified data in the client cache while the file is not open. | issue of modified data in the client cache while the file is not open. | |||
In this situation, any client that does not flush modified data to | In this situation, any client that does not flush modified data to | |||
the server on each close must ensure that the user receives | the server on each close must ensure that the user receives | |||
appropriate notification of the failure as a result of the revocation. | appropriate notification of the failure as a result of the revocation. | |||
Since such situations may require human action to correct problems, | Since such situations may require human action to correct problems, | |||
notification schemes in which the appropriate user or administrator is | notification schemes in which the appropriate user or administrator is | |||
notified may be necessary. Logging and console messages are typical | notified may be necessary. Logging and console messages are typical | |||
examples. | examples. | |||
</t> | </t> | |||
<t> | <t> | |||
If there is modified data on the client, it must not be flushed | If there is modified data on the client, it must not be flushed | |||
normally to the server. A client may attempt to provide a copy of the | normally to the server. A client may attempt to provide a copy of the | |||
file data as modified during the delegation under a different name in | file data as modified during the delegation under a different name in | |||
the file system namespace to ease recovery. Note that when the | the file system namespace to ease recovery. Note that when the | |||
client can determine that the file has not been modified by any other | client can determine that the file has not been modified by any other | |||
client, or when the client has a complete cached copy of the file in | client, or when the client has a complete cached copy of the file in | |||
question, such a saved copy of the client's view of the file may be of | question, such a saved copy of the client's view of the file may be of | |||
particular value for recovery. In another case, recovery using a copy | particular value for recovery. In another case, recovery using a copy | |||
of the file based partially on the client's cached data and partially | of the file based partially on the client's cached data and partially | |||
on the server's copy as modified by other clients will be anything but | on the server's copy as modified by other clients will be anything but | |||
straightforward, so clients may avoid saving file contents in these | straightforward, so clients may avoid saving file contents in these | |||
situations or specially mark the results to warn users of possible | situations or specially mark the results to warn users of possible | |||
problems. | problems. | |||
</t> | </t> | |||
<t> | <t> | |||
Saving of such modified data in delegation revocation situations | Saving of such modified data in delegation revocation situations | |||
may be limited to files of a certain size or might be used only when | may be limited to files of a certain size or might be used only when | |||
sufficient disk space is available within the target file system. | sufficient disk space is available within the target file system. | |||
Such saving may also be restricted to situations when the client has | Such saving may also be restricted to situations when the client has | |||
sufficient buffering resources to keep the cached copy available | sufficient buffering resources to keep the cached copy available | |||
until it is properly stored to the target file system. | until it is properly stored to the target file system. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section title="Attribute Caching" > | <section numbered="true" toc="default"> | |||
<t> | <name>Attribute Caching</name> | |||
<t> | ||||
This section pertains to the caching of a file's attributes on a client | This section pertains to the caching of a file's attributes on a client | |||
when that client does not hold a delegation on the file. | when that client does not hold a delegation on the file. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
The attributes discussed in this section do not include named | The attributes discussed in this section do not include named | |||
attributes. Individual named attributes are analogous to files, and | attributes. Individual named attributes are analogous to files, and | |||
caching of the data for these needs to be handled just as data caching | caching of the data for these needs to be handled just as data caching | |||
is for ordinary files. Similarly, LOOKUP results from an OPENATTR | is for ordinary files. Similarly, LOOKUP results from an OPENATTR | |||
directory (as well as the directory's contents) are to be cached on | directory (as well as the directory's contents) are to be cached on | |||
the same basis as any other pathnames. | the same basis as any other pathnames. | |||
</t> | </t> | |||
<t> | <t> | |||
Clients may cache file attributes obtained from the server and use | Clients may cache file attributes obtained from the server and use | |||
them to avoid subsequent GETATTR requests. Such caching is write | them to avoid subsequent GETATTR requests. Such caching is write | |||
through in that modification to file attributes is always done by | through in that modification to file attributes is always done by | |||
means of requests to the server and should not be done locally and | means of requests to the server and should not be done locally and | |||
should not be cached. The exception to this are modifications to attribut es that | should not be cached. The exception to this are modifications to attribut es that | |||
are intimately connected with data caching. Therefore, extending a | are intimately connected with data caching. Therefore, extending a | |||
file by writing data to the local data cache is reflected immediately | file by writing data to the local data cache is reflected immediately | |||
in the size as seen on the client without this change being | in the size as seen on the client without this change being | |||
immediately reflected on the server. Normally, such changes are not | immediately reflected on the server. Normally, such changes are not | |||
propagated directly to the server, but when the modified data is | propagated directly to the server, but when the modified data is | |||
flushed to the server, analogous attribute changes are made on the | flushed to the server, analogous attribute changes are made on the | |||
server. When OPEN delegation is in effect, the modified attributes | server. When OPEN delegation is in effect, the modified attributes | |||
may be returned to the server in reaction to a CB_RECALL call. | may be returned to the server in reaction to a CB_RECALL call. | |||
</t> | </t> | |||
<t> | <t> | |||
The result of local caching of attributes is that the attribute | The result of local caching of attributes is that the attribute | |||
caches maintained on individual clients will not be coherent. | caches maintained on individual clients will not be coherent. | |||
Changes made in one order on the server may be seen in a different | Changes made in one order on the server may be seen in a different | |||
order on one client and in a third order on another client. | order on one client and in a third order on another client. | |||
</t> | </t> | |||
<t> | <t> | |||
The typical file system application programming interfaces do not | The typical file system application programming interfaces do not | |||
provide means to atomically modify or interrogate attributes for | provide means to atomically modify or interrogate attributes for | |||
multiple files at the same time. The following rules provide an | multiple files at the same time. The following rules provide an | |||
environment where the potential incoherencies mentioned above can be | environment where the potential incoherencies mentioned above can be | |||
reasonably managed. These rules are derived from the practice of | reasonably managed. These rules are derived from the practice of | |||
previous NFS protocols. | previous NFS protocols. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
All attributes for a given file (per-fsid attributes excepted) are | All attributes for a given file (per-fsid attributes excepted) are | |||
cached as a unit at the client so that no non-serializability can | cached as a unit at the client so that no non-serializability can | |||
arise within the context of a single file. | arise within the context of a single file. | |||
</t> | </li> | |||
<t> | <li> | |||
An upper time boundary is maintained on how long a client cache entry | An upper time boundary is maintained on how long a client cache entry | |||
can be kept without being refreshed from the server. | can be kept without being refreshed from the server. | |||
</t> | </li> | |||
<t> | <li> | |||
When operations are performed that change attributes at the server, | When operations are performed that change attributes at the server, | |||
the updated attribute set is requested as part of the containing RPC. | the updated attribute set is requested as part of the containing RPC. | |||
This includes directory operations that update attributes indirectly. | This includes directory operations that update attributes indirectly. | |||
This is accomplished by following the modifying operation with a | This is accomplished by following the modifying operation with a | |||
GETATTR operation and then using the results of the GETATTR to update | GETATTR operation and then using the results of the GETATTR to update | |||
the client's cached attributes. | the client's cached attributes. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
Note that if the full set of attributes to be cached is requested by | Note that if the full set of attributes to be cached is requested by | |||
READDIR, the results can be cached by the client on the same basis as | READDIR, the results can be cached by the client on the same basis as | |||
attributes obtained via GETATTR. | attributes obtained via GETATTR. | |||
</t> | </t> | |||
<t> | <t> | |||
A client may validate its cached version of attributes for a file by | A client may validate its cached version of attributes for a file by | |||
fetching both the change and time_access attributes and assuming | fetching both the change and time_access attributes and assuming | |||
that if the change attribute has the same value as it did when the | that if the change attribute has the same value as it did when the | |||
attributes were cached, then no attributes other than time_access have | attributes were cached, then no attributes other than time_access have | |||
changed. The reason why time_access is also fetched is because many | changed. The reason why time_access is also fetched is because many | |||
servers operate in environments where the operation that updates | servers operate in environments where the operation that updates | |||
change does not update time_access. For example, POSIX file semantics | change does not update time_access. For example, POSIX file semantics | |||
do not update access time when a file is modified by the write system | do not update access time when a file is modified by the write system | |||
call <xref target="write_atime"/>. Therefore, the client that wants a cur rent time_access value | call <xref target="write_atime" format="default"/>. Therefore, the client that wants a current time_access value | |||
should fetch it with change during the attribute cache validation | should fetch it with change during the attribute cache validation | |||
processing and update its cached time_access. | processing and update its cached time_access. | |||
</t> | </t> | |||
<t> | <t> | |||
The client may maintain a cache of modified attributes for those | The client may maintain a cache of modified attributes for those | |||
attributes intimately connected with data of modified regular files | attributes intimately connected with data of modified regular files | |||
(size, time_modify, and change). Other than those three attributes, | (size, time_modify, and change). Other than those three attributes, | |||
the client MUST NOT maintain a cache of modified attributes. Instead, | the client <bcp14>MUST NOT</bcp14> maintain a cache of modified attributes . Instead, | |||
attribute changes are immediately sent to the server. | attribute changes are immediately sent to the server. | |||
</t> | </t> | |||
<t> | <t> | |||
In some operating environments, the equivalent to time_access is | In some operating environments, the equivalent to time_access is | |||
expected to be implicitly updated by each read of the content of the | expected to be implicitly updated by each read of the content of the | |||
file object. If an NFS client is caching the content of a file | file object. If an NFS client is caching the content of a file | |||
object, whether it is a regular file, directory, or symbolic link, the | object, whether it is a regular file, directory, or symbolic link, the | |||
client SHOULD NOT update the time_access attribute (via SETATTR or a | client <bcp14>SHOULD NOT</bcp14> update the time_access attribute (via SET ATTR or a | |||
small READ or READDIR request) on the server with each read that is | small READ or READDIR request) on the server with each read that is | |||
satisfied from cache. The reason is that this can defeat the | satisfied from cache. The reason is that this can defeat the | |||
performance benefits of caching content, especially since an explicit | performance benefits of caching content, especially since an explicit | |||
SETATTR of time_access may alter the change attribute on the server. | SETATTR of time_access may alter the change attribute on the server. | |||
If the change attribute changes, clients that are caching the content | If the change attribute changes, clients that are caching the content | |||
will think the content has changed, and will re-read unmodified data | will think the content has changed, and will re-read unmodified data | |||
from the server. Nor is the client encouraged to maintain a modified | from the server. Nor is the client encouraged to maintain a modified | |||
version of time_access in its cache, since the client either would | version of time_access in its cache, since the client either would | |||
eventually have to write the access time to the server | eventually have to write the access time to the server | |||
with bad performance effects or never update the | with bad performance effects or never update the | |||
server's time_access, thereby resulting in a situation where an | server's time_access, thereby resulting in a situation where an | |||
application that caches access time between a close and open of | application that caches access time between a close and open of | |||
the same file observes the access time oscillating between the past and | the same file observes the access time oscillating between the past and | |||
present. The time_access attribute always means the time of last | present. The time_access attribute always means the time of last | |||
access to a file by a read that was satisfied by the server. This way | access to a file by a read that was satisfied by the server. This way | |||
clients will tend to see only time_access changes that go forward in | clients will tend to see only time_access changes that go forward in | |||
time. | time. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Data and Metadata Caching and Memory Mapped Files" > | <section numbered="true" toc="default"> | |||
<t> | <name>Data and Metadata Caching and Memory Mapped Files</name> | |||
<t> | ||||
Some operating environments include the capability for an application | Some operating environments include the capability for an application | |||
to map a file's content into the application's address space. Each | to map a file's content into the application's address space. Each | |||
time the application accesses a memory location that corresponds to a | time the application accesses a memory location that corresponds to a | |||
block that has not been loaded into the address space, a page fault | block that has not been loaded into the address space, a page fault | |||
occurs and the file is read (or if the block does not exist in the | occurs and the file is read (or if the block does not exist in the | |||
file, the block is allocated and then instantiated in the | file, the block is allocated and then instantiated in the | |||
application's address space). | application's address space). | |||
</t> | </t> | |||
<t> | <t> | |||
As long as each memory-mapped access to the file requires a page | As long as each memory-mapped access to the file requires a page | |||
fault, the relevant attributes of the file that are used to detect | fault, the relevant attributes of the file that are used to detect | |||
access and modification (time_access, time_metadata, time_modify, and | access and modification (time_access, time_metadata, time_modify, and | |||
change) will be updated. However, in many operating environments, | change) will be updated. However, in many operating environments, | |||
when page faults are not required, these attributes will not be updated | when page faults are not required, these attributes will not be updated | |||
on reads or updates to the file via memory access (regardless of | on reads or updates to the file via memory access (regardless of | |||
whether the file is local or is accessed remotely). A client or | whether the file is local or is accessed remotely). A client or | |||
server MAY fail to update attributes of a file that is being accessed | server <bcp14>MAY</bcp14> fail to update attributes of a file that is bein g accessed | |||
via memory-mapped I/O. This has several implications: | via memory-mapped I/O. This has several implications: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If there is an application on the server that has memory mapped a file | If there is an application on the server that has memory mapped a file | |||
that a client is also accessing, the client may not be able to get a | that a client is also accessing, the client may not be able to get a | |||
consistent value of the change attribute to determine | consistent value of the change attribute to determine | |||
whether or not its cache is stale. A server that knows that | whether or not its cache is stale. A server that knows that | |||
the file is memory-mapped could always pessimistically | the file is memory-mapped could always pessimistically | |||
return updated values for change so as to force the | return updated values for change so as to force the | |||
application to always get the most up-to-date data | application to always get the most up-to-date data | |||
and metadata for the file. However, due to the negative performance | and metadata for the file. However, due to the negative performance | |||
implications of this, such behavior is OPTIONAL. | implications of this, such behavior is <bcp14>OPTIONAL</bcp14>. | |||
</t> | </li> | |||
<t> | <li> | |||
If the memory-mapped file is not being modified on the server, and | If the memory-mapped file is not being modified on the server, and | |||
instead is just being read by an application via the memory-mapped | instead is just being read by an application via the memory-mapped | |||
interface, the client will not see an updated time_access attribute. | interface, the client will not see an updated time_access attribute. | |||
However, in many operating environments, neither will any process | However, in many operating environments, neither will any process | |||
running on the server. Thus, NFS clients are at no disadvantage with | running on the server. Thus, NFS clients are at no disadvantage with | |||
respect to local processes. | respect to local processes. | |||
</t> | </li> | |||
<t> | <li> | |||
If there is another client that is memory mapping the file, and if | If there is another client that is memory mapping the file, and if | |||
that client is holding an OPEN_DELEGATE_WRITE delegation, the same set of issues as | that client is holding an OPEN_DELEGATE_WRITE delegation, the same set of issues as | |||
discussed in the previous two bullet points apply. So, when a server | discussed in the previous two bullet points apply. So, when a server | |||
does a CB_GETATTR to a file that the client has modified in its cache, | does a CB_GETATTR to a file that the client has modified in its cache, | |||
the reply from CB_GETATTR will not necessarily be accurate. As | the reply from CB_GETATTR will not necessarily be accurate. As | |||
discussed earlier, the client's obligation is to report that the file | discussed earlier, the client's obligation is to report that the file | |||
has been modified since the delegation was granted, not whether it has | has been modified since the delegation was granted, not whether it has | |||
been modified again between successive CB_GETATTR calls, and the | been modified again between successive CB_GETATTR calls, and the | |||
server MUST assume that any file the client has modified in cache has | server <bcp14>MUST</bcp14> assume that any file the client has modifie d in cache has | |||
been modified again between successive CB_GETATTR calls. Depending on | been modified again between successive CB_GETATTR calls. Depending on | |||
the nature of the client's memory management system, this weak | the nature of the client's memory management system, this weak | |||
obligation may not be possible. A client MAY return stale information | obligation may not be possible. A client <bcp14>MAY</bcp14> return st ale information | |||
in CB_GETATTR whenever the file is memory-mapped. | in CB_GETATTR whenever the file is memory-mapped. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
The mixture of memory mapping and byte-range locking on the same file is | The mixture of memory mapping and byte-range locking on the same file is | |||
problematic. Consider the following scenario, where a page size on | problematic. Consider the following scenario, where a page size on | |||
each client is 8192 bytes. | each client is 8192 bytes. | |||
<list style="symbols"> | ||||
<t> | ||||
Client A memory maps the first page (8192 bytes) of file X. | ||||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Client A memory maps the first page (8192 bytes) of file X. | ||||
</li> | ||||
<li> | ||||
Client B memory maps the first page (8192 bytes) of file X. | Client B memory maps the first page (8192 bytes) of file X. | |||
</t> | </li> | |||
<t> | <li> | |||
Client A WRITE_LT locks the first 4096 bytes. | Client A WRITE_LT locks the first 4096 bytes. | |||
</t> | </li> | |||
<t> | <li> | |||
Client B WRITE_LT locks the second 4096 bytes. | Client B WRITE_LT locks the second 4096 bytes. | |||
</t> | </li> | |||
<t> | <li> | |||
Client A, via a STORE instruction, modifies part of its locked byt e-range. | Client A, via a STORE instruction, modifies part of its locked byt e-range. | |||
</t> | </li> | |||
<t> | <li> | |||
Simultaneous to client A, client B executes a STORE on part of its | Simultaneous to client A, client B executes a STORE on part of its | |||
locked byte-range. | locked byte-range. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Here the challenge is for each client to resynchronize to get a | Here the challenge is for each client to resynchronize to get a | |||
correct view of the first page. In many operating environments, the | correct view of the first page. In many operating environments, the | |||
virtual memory management systems on each client only know a page is | virtual memory management systems on each client only know a page is | |||
modified, not that a subset of the page corresponding to the | modified, not that a subset of the page corresponding to the | |||
respective lock byte-ranges has been modified. So it is not possible for | respective lock byte-ranges has been modified. So it is not possible for | |||
each client to do the right thing, which is to write to the | each client to do the right thing, which is to write to the | |||
server only that portion of the page that is locked. For example, if | server only that portion of the page that is locked. For example, if | |||
client A simply writes out the page, and then client B writes out the | client A simply writes out the page, and then client B writes out the | |||
page, client A's data is lost. | page, client A's data is lost. | |||
</t> | </t> | |||
<t> | <t> | |||
Moreover, if mandatory locking is enabled on the file, then we have a | Moreover, if mandatory locking is enabled on the file, then we have a | |||
different problem. When clients A and B execute the STORE instructions, | different problem. When clients A and B execute the STORE instructions, | |||
the resulting page faults require a byte-range lock on the entire page. | the resulting page faults require a byte-range lock on the entire page. | |||
Each client then tries to extend their locked range to the entire | Each client then tries to extend their locked range to the entire | |||
page, which results in a deadlock. Communicating the NFS4ERR_DEADLOCK | page, which results in a deadlock. Communicating the NFS4ERR_DEADLOCK | |||
error to a STORE instruction is difficult at best. | error to a STORE instruction is difficult at best. | |||
</t> | </t> | |||
<t> | <t> | |||
If a client is locking the entire memory-mapped file, there is no | If a client is locking the entire memory-mapped file, there is no | |||
problem with advisory or mandatory byte-range locking, at least until the | problem with advisory or mandatory byte-range locking, at least until the | |||
client unlocks a byte-range in the middle of the file. | client unlocks a byte-range in the middle of the file. | |||
</t> | ||||
<t> | ||||
Given the above issues, the following are permitted: | ||||
<list style="symbols"> | ||||
<t> | ||||
Clients and servers MAY deny memory mapping a file for which they know | ||||
there are | ||||
byte-range locks. | ||||
</t> | </t> | |||
<t> | <t> | |||
Clients and servers MAY deny a byte-range lock on a file they know is | Given the above issues, the following are permitted: | |||
memory-mapped. | ||||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
A client MAY deny memory mapping a file that it knows requires | <li> | |||
Clients and servers <bcp14>MAY</bcp14> deny memory mapping a file for | ||||
which they know there are | ||||
byte-range locks. | ||||
</li> | ||||
<li> | ||||
Clients and servers <bcp14>MAY</bcp14> deny a byte-range lock on a fil | ||||
e they know is | ||||
memory-mapped. | ||||
</li> | ||||
<li> | ||||
A client <bcp14>MAY</bcp14> deny memory mapping a file that it knows r | ||||
equires | ||||
mandatory locking for I/O. If mandatory locking is enabled after the | mandatory locking for I/O. If mandatory locking is enabled after the | |||
file is opened and mapped, the client MAY deny the application further | file is opened and mapped, the client <bcp14>MAY</bcp14> deny the appl ication further | |||
access to its mapped file. | access to its mapped file. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section anchor="without_dir_deleg" numbered="true" toc="default"> | |||
<section title="Name and Directory Caching without Directory Delegations" | <name>Name and Directory Caching without Directory Delegations</name> | |||
anchor="without_dir_deleg"> | <t> | |||
<t> | ||||
The NFSv4.1 directory delegation facility | The NFSv4.1 directory delegation facility | |||
(described in <xref target="dir_deleg" /> below) is OPTIONAL | (described in <xref target="dir_deleg" format="default"/> below) is <bcp14 >OPTIONAL</bcp14> | |||
for servers to implement. Even where it is | for servers to implement. Even where it is | |||
implemented, it may not always be functional because of resource | implemented, it may not always be functional because of resource | |||
availability issues or other constraints. Thus, it is | availability issues or other constraints. Thus, it is | |||
important to understand how name and directory caching are done | important to understand how name and directory caching are done | |||
in the absence of directory delegations. These topics are | in the absence of directory delegations. These topics are | |||
discussed in the next two subsections. | discussed in the next two subsections. | |||
</t> | </t> | |||
<section anchor="name_caching" title="Name Caching" > | <section anchor="name_caching" numbered="true" toc="default"> | |||
<t> | <name>Name Caching</name> | |||
<t> | ||||
The results of LOOKUP and READDIR operations may be cached to avoid | The results of LOOKUP and READDIR operations may be cached to avoid | |||
the cost of subsequent LOOKUP operations. Just as in the case of | the cost of subsequent LOOKUP operations. Just as in the case of | |||
attribute caching, inconsistencies may arise among the various client | attribute caching, inconsistencies may arise among the various client | |||
caches. To mitigate the effects of these inconsistencies and given | caches. To mitigate the effects of these inconsistencies and given | |||
the context of typical file system APIs, an upper time boundary is | the context of typical file system APIs, an upper time boundary is | |||
maintained for how long a client name cache entry can be kept without | maintained for how long a client name cache entry can be kept without | |||
verifying that the entry has not been made invalid by a directory | verifying that the entry has not been made invalid by a directory | |||
change operation performed by another client. | change operation performed by another client. | |||
</t> | </t> | |||
<t> | <t> | |||
When a client is not making changes to a directory for which there | When a client is not making changes to a directory for which there | |||
exist name cache entries, the client needs to periodically fetch | exist name cache entries, the client needs to periodically fetch | |||
attributes for that directory to ensure that it is not being modified. | attributes for that directory to ensure that it is not being modified. | |||
After determining that no modification has occurred, the expiration | After determining that no modification has occurred, the expiration | |||
time for the associated name cache entries may be updated to be the | time for the associated name cache entries may be updated to be the | |||
current time plus the name cache staleness bound. | current time plus the name cache staleness bound. | |||
</t> | </t> | |||
<t> | <t> | |||
When a client is making changes to a given directory, it needs to | When a client is making changes to a given directory, it needs to | |||
determine whether there have been changes made to the directory by | determine whether there have been changes made to the directory by | |||
other clients. It does this by using the change attribute as reported | other clients. It does this by using the change attribute as reported | |||
before and after the directory operation in the associated | before and after the directory operation in the associated | |||
change_info4 value returned for the operation. The server is able to | change_info4 value returned for the operation. The server is able to | |||
communicate to the client whether the change_info4 data is provided | communicate to the client whether the change_info4 data is provided | |||
atomically with respect to the directory operation. If the change | atomically with respect to the directory operation. If the change | |||
values are provided atomically, the client has a basis for determining, | values are provided atomically, the client has a basis for determining, | |||
given proper care, whether other clients are modifying the directory | given proper care, whether other clients are modifying the directory | |||
in question. | in question. | |||
</t> | </t> | |||
<t> | <t> | |||
The simplest way to enable the client to make this determination is | The simplest way to enable the client to make this determination is | |||
for the client to serialize all changes made to a specific directory. | for the client to serialize all changes made to a specific directory. | |||
When this is done, and the server provides before and after values of th e | When this is done, and the server provides before and after values of th e | |||
change attribute atomically, the client can simply compare the | change attribute atomically, the client can simply compare the | |||
after value of the change attribute from one operation on a | after value of the change attribute from one operation on a | |||
directory with the before value on the subsequent operation | directory with the before value on the subsequent operation | |||
modifying that directory. When these are equal, the client is | modifying that directory. When these are equal, the client is | |||
assured that no other client is modifying the directory in question. | assured that no other client is modifying the directory in question. | |||
</t> | </t> | |||
<t> | <t> | |||
When such serialization is not used, and there may be multiple | When such serialization is not used, and there may be multiple | |||
simultaneous outstanding operations modifying a single directory sent | simultaneous outstanding operations modifying a single directory sent | |||
from a single client, making this sort of determination can be more | from a single client, making this sort of determination can be more | |||
complicated. If two such operations | complicated. If two such operations | |||
complete in a different order than they were actually performed, | complete in a different order than they were actually performed, | |||
that might give an appearance consistent with modification being | that might give an appearance consistent with modification being | |||
made by another client. Where this appears to happen, the client | made by another client. Where this appears to happen, the client | |||
needs to await the completion of all such modifications that were | needs to await the completion of all such modifications that were | |||
started previously, to see if the outstanding before and after | started previously, to see if the outstanding before and after | |||
change numbers can be sorted into a chain such that the before | change numbers can be sorted into a chain such that the before | |||
value of one change number matches the after value of a previous | value of one change number matches the after value of a previous | |||
one, in a chain consistent with this client being the only one | one, in a chain consistent with this client being the only one | |||
modifying the directory. | modifying the directory. | |||
</t> | </t> | |||
<t> | <t> | |||
In either of these cases, the client is able to determine whether | In either of these cases, the client is able to determine whether | |||
the directory is being modified by another client. | the directory is being modified by another client. | |||
If the comparison indicates that the directory was updated by | If the comparison indicates that the directory was updated by | |||
another client, the name cache associated with the modified directory | another client, the name cache associated with the modified directory | |||
is purged from the client. If the comparison indicates no | is purged from the client. If the comparison indicates no | |||
modification, the name cache can be updated on the client to reflect | modification, the name cache can be updated on the client to reflect | |||
the directory operation and the associated timeout can be extended. The | the directory operation and the associated timeout can be extended. The | |||
post-operation change value needs to be saved as the basis for future | post-operation change value needs to be saved as the basis for future | |||
change_info4 comparisons. | change_info4 comparisons. | |||
</t> | </t> | |||
<t> | <t> | |||
As demonstrated by the scenario above, name caching requires that the | As demonstrated by the scenario above, name caching requires that the | |||
client revalidate name cache data by inspecting the change attribute | client revalidate name cache data by inspecting the change attribute | |||
of a directory at the point when the name cache item was cached. This | of a directory at the point when the name cache item was cached. This | |||
requires that the server update the change attribute for directories | requires that the server update the change attribute for directories | |||
when the contents of the corresponding directory is modified. For a | when the contents of the corresponding directory is modified. For a | |||
client to use the change_info4 information appropriately and | client to use the change_info4 information appropriately and | |||
correctly, the server must report the pre- and post-operation change | correctly, the server must report the pre- and post-operation change | |||
attribute values atomically. When the server is unable to report the | attribute values atomically. When the server is unable to report the | |||
before and after values atomically with respect to the directory | before and after values atomically with respect to the directory | |||
operation, the server must indicate that fact in the change_info4 | operation, the server must indicate that fact in the change_info4 | |||
return value. When the information is not atomically reported, the | return value. When the information is not atomically reported, the | |||
client should not assume that other clients have not changed the | client should not assume that other clients have not changed the | |||
directory. | directory. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Directory Caching" > | <section numbered="true" toc="default"> | |||
<t> | <name>Directory Caching</name> | |||
<t> | ||||
The results of READDIR operations may be used to avoid subsequent | The results of READDIR operations may be used to avoid subsequent | |||
READDIR operations. Just as in the cases of attribute and name | READDIR operations. Just as in the cases of attribute and name | |||
caching, inconsistencies may arise among the various client caches. To | caching, inconsistencies may arise among the various client caches. To | |||
mitigate the effects of these inconsistencies, and given the context of | mitigate the effects of these inconsistencies, and given the context of | |||
typical file system APIs, the following rules should be followed: | typical file system APIs, the following rules should be followed: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Cached READDIR information for a directory that is not obtained in a | Cached READDIR information for a directory that is not obtained in a | |||
single READDIR operation must always be a consistent snapshot of | single READDIR operation must always be a consistent snapshot of | |||
directory contents. This is determined by using a GETATTR before th e | directory contents. This is determined by using a GETATTR before th e | |||
first READDIR and after the last READDIR that contributes to the | first READDIR and after the last READDIR that contributes to the | |||
cache. | cache. | |||
</t> | </li> | |||
<t> | <li> | |||
An upper time boundary is maintained to indicate the length of time a | An upper time boundary is maintained to indicate the length of time a | |||
directory cache entry is considered valid before the client must | directory cache entry is considered valid before the client must | |||
revalidate the cached information. | revalidate the cached information. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
The revalidation technique parallels that discussed in the case of | The revalidation technique parallels that discussed in the case of | |||
name caching. When the client is not changing the directory in | name caching. When the client is not changing the directory in | |||
question, checking the change attribute of the directory with GETATTR | question, checking the change attribute of the directory with GETATTR | |||
is adequate. The lifetime of the cache entry can be extended at these | is adequate. The lifetime of the cache entry can be extended at these | |||
checkpoints. When a client is modifying the directory, the client | checkpoints. When a client is modifying the directory, the client | |||
needs to use the change_info4 data to determine whether there are | needs to use the change_info4 data to determine whether there are | |||
other clients modifying the directory. If it is determined that no | other clients modifying the directory. If it is determined that no | |||
other client modifications are occurring, the client may update its | other client modifications are occurring, the client may update its | |||
directory cache to reflect its own changes. | directory cache to reflect its own changes. | |||
</t> | </t> | |||
<t> | <t> | |||
As demonstrated previously, directory caching requires that the client | As demonstrated previously, directory caching requires that the client | |||
revalidate directory cache data by inspecting the change attribute of | revalidate directory cache data by inspecting the change attribute of | |||
a directory at the point when the directory was cached. This requires | a directory at the point when the directory was cached. This requires | |||
that the server update the change attribute for directories when the | that the server update the change attribute for directories when the | |||
contents of the corresponding directory is modified. For a client to | contents of the corresponding directory is modified. For a client to | |||
use the change_info4 information appropriately and correctly, the | use the change_info4 information appropriately and correctly, the | |||
server must report the pre- and post-operation change attribute values | server must report the pre- and post-operation change attribute values | |||
atomically. When the server is unable to report the before and after | atomically. When the server is unable to report the before and after | |||
values atomically with respect to the directory operation, the server | values atomically with respect to the directory operation, the server | |||
must indicate that fact in the change_info4 return value. When the | must indicate that fact in the change_info4 return value. When the | |||
information is not atomically reported, the client should not assume | information is not atomically reported, the client should not assume | |||
that other clients have not changed the directory. | that other clients have not changed the directory. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section title="Directory Delegations" anchor="dir_deleg"> | <section anchor="dir_deleg" numbered="true" toc="default"> | |||
<section title="Introduction to Directory Delegations"> | <name>Directory Delegations</name> | |||
<t> | <section numbered="true" toc="default"> | |||
<name>Introduction to Directory Delegations</name> | ||||
<t> | ||||
Directory caching for the NFSv4.1 protocol, as previously | Directory caching for the NFSv4.1 protocol, as previously | |||
described, is similar to file | described, is similar to file | |||
caching in previous versions. Clients typically cache | caching in previous versions. Clients typically cache | |||
directory information for | directory information for | |||
a duration determined by the client. At the end of a predefined | a duration determined by the client. At the end of a predefined | |||
timeout, the client will query the server to see if the directory has | timeout, the client will query the server to see if the directory has | |||
been updated. By caching attributes, clients reduce the number of | been updated. By caching attributes, clients reduce the number of | |||
GETATTR calls made to the server to validate attributes. Furthermore, | GETATTR calls made to the server to validate attributes. Furthermore, | |||
frequently accessed files and directories, such as the current | frequently accessed files and directories, such as the current | |||
working directory, have their attributes cached on the client so that | working directory, have their attributes cached on the client so that | |||
some NFS operations can be performed without having to make an RPC | some NFS operations can be performed without having to make an RPC | |||
call. By caching name and inode information about most recently | call. By caching name and inode information about most recently | |||
looked up entries in a Directory Name Lookup Cache (DNLC), clients do | looked up entries in a Directory Name Lookup Cache (DNLC), clients do | |||
not need to send LOOKUP calls to the server every time these files | not need to send LOOKUP calls to the server every time these files | |||
are accessed. | are accessed. | |||
</t> | </t> | |||
<t> | <t> | |||
This caching approach works reasonably well at reducing network | This caching approach works reasonably well at reducing network | |||
traffic in many environments. However, it does not address | traffic in many environments. However, it does not address | |||
environments where there are numerous queries for files that do not | environments where there are numerous queries for files that do not | |||
exist. In these cases of "misses", the client sends requests to | exist. In these cases of "misses", the client sends requests to | |||
the server in order to provide reasonable application semantics and | the server in order to provide reasonable application semantics and | |||
promptly detect the creation of new directory entries. Examples of | promptly detect the creation of new directory entries. Examples of | |||
high miss activity are compilation in software development | high miss activity are compilation in software development | |||
environments. The current behavior of NFS limits its potential | environments. The current behavior of NFS limits its potential | |||
scalability and wide-area sharing effectiveness in these types of | scalability and wide-area sharing effectiveness in these types of | |||
environments. Other distributed stateful file system architectures | environments. Other distributed stateful file system architectures | |||
such as AFS and DFS have proven that adding state around directory | such as AFS and DFS have proven that adding state around directory | |||
contents can greatly reduce network traffic in high-miss | contents can greatly reduce network traffic in high-miss | |||
environments. | environments. | |||
</t> | </t> | |||
<t> | <t> | |||
Delegation of directory contents is an OPTIONAL feature of NFSv4.1. | Delegation of directory contents is an <bcp14>OPTIONAL</bcp14> feature o | |||
f NFSv4.1. | ||||
Directory delegations provide similar traffic reduction | Directory delegations provide similar traffic reduction | |||
benefits as with file delegations. By allowing clients to cache | benefits as with file delegations. By allowing clients to cache | |||
directory contents (in a read-only fashion) while being notified of | directory contents (in a read-only fashion) while being notified of | |||
changes, the client can avoid making frequent requests to interrogate | changes, the client can avoid making frequent requests to interrogate | |||
the contents of slowly-changing directories, reducing network traffic | the contents of slowly-changing directories, reducing network traffic | |||
and improving client performance. It can also simplify the task of | and improving client performance. It can also simplify the task of | |||
determining whether other clients are making changes to the directory | determining whether other clients are making changes to the directory | |||
when the client itself is making many changes to the directory and | when the client itself is making many changes to the directory and | |||
changes are not serialized. | changes are not serialized. | |||
</t> | </t> | |||
<t> | <t> | |||
Directory delegations allow improved namespace cache consistency to be | Directory delegations allow improved namespace cache consistency to be | |||
achieved through delegations and synchronous recalls, in the absence | achieved through delegations and synchronous recalls, in the absence | |||
of notifications. In addition, if time-based consistency is | of notifications. In addition, if time-based consistency is | |||
sufficient, asynchronous notifications can provide performance | sufficient, asynchronous notifications can provide performance | |||
benefits for the client, and possibly the server, under some common | benefits for the client, and possibly the server, under some common | |||
operating conditions such as slowly-changing and/or very large | operating conditions such as slowly-changing and/or very large | |||
directories. | directories. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Directory Delegation Design"> | <section numbered="true" toc="default"> | |||
<t> | <name>Directory Delegation Design</name> | |||
<t> | ||||
NFSv4.1 introduces the GET_DIR_DELEGATION | NFSv4.1 introduces the GET_DIR_DELEGATION | |||
(<xref target="OP_GET_DIR_DELEGATION" />) operation to allow the | (<xref target="OP_GET_DIR_DELEGATION" format="default"/>) operation to a llow the | |||
client to ask for a | client to ask for a | |||
directory delegation. The delegation covers directory attributes and | directory delegation. The delegation covers directory attributes and | |||
all entries in the directory. If either of these change, the | all entries in the directory. If either of these change, the | |||
delegation will be recalled synchronously. The operation causing the | delegation will be recalled synchronously. The operation causing the | |||
recall will have to wait before the recall is complete. Any changes | recall will have to wait before the recall is complete. Any changes | |||
to directory entry attributes will not cause the delegation to be | to directory entry attributes will not cause the delegation to be | |||
recalled. | recalled. | |||
</t> | </t> | |||
<t> | <t> | |||
In addition to asking for delegations, a client can also ask for | In addition to asking for delegations, a client can also ask for | |||
notifications for certain events. These events include changes to | notifications for certain events. These events include changes to | |||
the directory's attributes and/or its contents. If a client asks for | the directory's attributes and/or its contents. If a client asks for | |||
notification for a certain event, the server will notify the client | notification for a certain event, the server will notify the client | |||
when that event occurs. This will not result in the delegation being | when that event occurs. This will not result in the delegation being | |||
recalled for that client. The notifications are asynchronous and | recalled for that client. The notifications are asynchronous and | |||
provide a way of avoiding recalls in situations where a directory is | provide a way of avoiding recalls in situations where a directory is | |||
changing enough that the pure recall model may not be effective while | changing enough that the pure recall model may not be effective while | |||
trying to allow the client to get substantial benefit. In the absence | trying to allow the client to get substantial benefit. In the absence | |||
of notifications, once the delegation is recalled the client has to | of notifications, once the delegation is recalled the client has to | |||
refresh its directory cache; this might not be very efficient for | refresh its directory cache; this might not be very efficient for | |||
very large directories. | very large directories. | |||
</t> | </t> | |||
<t> | <t> | |||
The delegation is read-only and the client may not make changes to | The delegation is read-only and the client may not make changes to | |||
the directory other than by performing NFSv4.1 operations that modify | the directory other than by performing NFSv4.1 operations that modify | |||
the directory or the associated file attributes so that the server | the directory or the associated file attributes so that the server | |||
has knowledge of these changes. In order to keep the client's | has knowledge of these changes. In order to keep the client's | |||
namespace synchronized with that of the server, the server will notify | namespace synchronized with that of the server, the server will notify | |||
the delegation-holding client (assuming it has requested | the delegation-holding client (assuming it has requested | |||
notifications) of the changes made as a result of that client's | notifications) of the changes made as a result of that client's | |||
directory-modifying operations. This is to avoid any need for | directory-modifying operations. This is to avoid any need for | |||
that client to send subsequent GETATTR or READDIR operations | that client to send subsequent GETATTR or READDIR operations | |||
to the server. If a single client is holding the delegation | to the server. If a single client is holding the delegation | |||
and that client makes any changes to the directory (i.e., the | and that client makes any changes to the directory (i.e., the | |||
changes are made via operations sent on a session | changes are made via operations sent on a session | |||
associated with the client ID holding the delegation), the | associated with the client ID holding the delegation), the | |||
delegation will not be recalled. Multiple clients may hold a delegation | delegation will not be recalled. Multiple clients may hold a delegation | |||
on the same directory, but if any such client modifies the directory, | on the same directory, but if any such client modifies the directory, | |||
the server MUST recall the delegation from the other clients, | the server <bcp14>MUST</bcp14> recall the delegation from the other clie nts, | |||
unless those clients have made provisions to be notified of that | unless those clients have made provisions to be notified of that | |||
sort of modification. | sort of modification. | |||
</t> | </t> | |||
<t> | <t> | |||
Delegations can be recalled by the server at any time. Normally, the | Delegations can be recalled by the server at any time. Normally, the | |||
server will recall the delegation when the directory changes in a way | server will recall the delegation when the directory changes in a way | |||
that is not covered by the notification, or when the directory | that is not covered by the notification, or when the directory | |||
changes and notifications have not been requested. | changes and notifications have not been requested. | |||
If another client removes the directory for | If another client removes the directory for | |||
which a delegation has been granted, the server will recall the | which a delegation has been granted, the server will recall the | |||
delegation. | delegation. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Attributes in Support of Directory Notifications"> | <section numbered="true" toc="default"> | |||
<t> | <name>Attributes in Support of Directory Notifications</name> | |||
See <xref target="dir_not_attrs" /> for a description of the attributes | <t> | |||
See <xref target="dir_not_attrs" format="default"/> for a description of | ||||
the attributes | ||||
associated with directory notifications. | associated with directory notifications. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="Directory Delegation Recall"> | <name>Directory Delegation Recall</name> | |||
<t> | <t> | |||
The server will recall the directory delegation by sending a callback | The server will recall the directory delegation by sending a callback | |||
to the client. It will use the same callback procedure as used for | to the client. It will use the same callback procedure as used for | |||
recalling file delegations. The server will recall the delegation | recalling file delegations. The server will recall the delegation | |||
when the directory changes in a way that is not covered by the | when the directory changes in a way that is not covered by the | |||
notification. However, the server need not recall the delegation if | notification. However, the server need not recall the delegation if | |||
attributes of an entry within the directory change. | attributes of an entry within the directory change. | |||
</t> | </t> | |||
<t> | <t> | |||
If the | If the | |||
server notices that handing out a delegation for a directory is | server notices that handing out a delegation for a directory is | |||
causing too many notifications to be sent out, it may decide to | causing too many notifications to be sent out, it may decide to | |||
not hand out delegations for that directory and/or recall those already | not hand out delegations for that directory and/or recall those already | |||
granted. If a client tries to remove the directory for which | granted. If a client tries to remove the directory for which | |||
a delegation has been granted, the server will recall all associated del egations. | a delegation has been granted, the server will recall all associated del egations. | |||
</t> | </t> | |||
<t> | <t> | |||
The implementation sections for a number | The implementation sections for a number | |||
of operations describe situations in which notification or | of operations describe situations in which notification or | |||
delegation recall would be required under some common circumstances. | delegation recall would be required under some common circumstances. | |||
In this regard, a similar set of caveats to those listed | In this regard, a similar set of caveats to those listed | |||
in <xref target="deleg_and_cb" /> apply. | in <xref target="deleg_and_cb" format="default"/> apply. | |||
<list style="symbols"> | ||||
<t> | ||||
For CREATE, see <xref target="OP_CREATE_IMPLEMENTATION" />. | ||||
</t> | ||||
<t> | ||||
For LINK, see <xref target="OP_LINK_IMPLEMENTATION" />. | ||||
</t> | ||||
<t> | ||||
For OPEN, see <xref target="OP_OPEN_IMPLEMENTATION" />. | ||||
</t> | ||||
<t> | ||||
For REMOVE, see <xref target="OP_REMOVE_IMPLEMENTATION" />. | ||||
</t> | ||||
<t> | ||||
For RENAME, see <xref target="OP_RENAME_IMPLEMENTATION" />. | ||||
</t> | </t> | |||
<ul spacing="normal"> | ||||
<li> | ||||
For CREATE, see <xref target="OP_CREATE_IMPLEMENTATION" format="defa | ||||
ult"/>. | ||||
</li> | ||||
<li> | ||||
For LINK, see <xref target="OP_LINK_IMPLEMENTATION" format="default" | ||||
/>. | ||||
</li> | ||||
<li> | ||||
For OPEN, see <xref target="OP_OPEN_IMPLEMENTATION" format="default" | ||||
/>. | ||||
</li> | ||||
<li> | ||||
For REMOVE, see <xref target="OP_REMOVE_IMPLEMENTATION" format="defa | ||||
ult"/>. | ||||
</li> | ||||
<li> | ||||
For RENAME, see <xref target="OP_RENAME_IMPLEMENTATION" format="defa | ||||
ult"/>. | ||||
</li> | ||||
<li> | ||||
For SETATTR, see <xref target="OP_SETATTR_IMPLEMENTATION" format="de | ||||
fault"/>. | ||||
</li> | ||||
</ul> | ||||
</section> | ||||
<section numbered="true" toc="default"> | ||||
<name>Directory Delegation Recovery</name> | ||||
<t> | <t> | |||
For SETATTR, see <xref target="OP_SETATTR_IMPLEMENTATION" />. | ||||
</t> | ||||
</list> | ||||
</t> | ||||
</section> | ||||
<section title="Directory Delegation Recovery"> | ||||
<t> | ||||
Recovery from client or server restart for state on regular files | Recovery from client or server restart for state on regular files | |||
has two main goals: avoiding the necessity of | has two main goals: avoiding the necessity of | |||
breaking application guarantees with respect to locked files and | breaking application guarantees with respect to locked files and | |||
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 anchor="NEW11" numbered="true" toc="default"> | ||||
</section> | <name>Multi-Server Namespace</name> | |||
</section> | <t> | |||
<!-- $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" | ||||
title="Multi-Server Namespace"> | ||||
<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 OPTIONAL 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 paths 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 title="Terminology" | <section anchor="SEC11-TERM" numbered="true" toc="default"> | |||
anchor="SEC11-TERM"> | <name>Terminology</name> | |||
<t> | <t> | |||
In this section as a whole (i.e. within all of <xref target="NEW11"/>), | In this section as a whole (i.e., within all of <xref target="NEW11" forma | |||
t="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 which 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 | |||
structures is referred to as a "client id string". | structures is referred to as a "client id string". | |||
</t> | </t> | |||
<section anchor="SEC11-TERM-trunking" numbered="true" toc="default"> | ||||
<section title="Terminology Related to Trunking" | <name>Terminology Related to Trunking</name> | |||
anchor="SEC11-TERM-trunking"> | <t> | |||
<t> | ||||
It is particularly important to clarify the distinction | It is particularly important to clarify the distinction | |||
between trunking detection and | between trunking detection and trunking discovery. | |||
trunking discovery. The definitions we present are | The definitions we present are applicable to all | |||
applicable to all | ||||
minor versions of NFSv4, but we will focus on how | minor versions of NFSv4, but we will focus on how | |||
these | these terms apply to NFS version 4.1. | |||
terms apply to NFS version 4.1. | </t> | |||
<list style ='symbols'> | <ul spacing="normal"> | |||
<t> | <li> | |||
<t> | ||||
Trunking detection refers to ways of deciding whether two | Trunking detection refers to ways of deciding whether two | |||
specific network | specific network | |||
addresses are connected to the same NFSv4 server. The | addresses are connected to the same NFSv4 server. The | |||
means available to make this determination depends on the protocol | means available to make this determination depends on the protocol | |||
version, and, in some cases, on the client implementation. | version, and, in some cases, on the client implementation. | |||
<vspace blankLines="1"/> | </t> | |||
<t> | ||||
In the case of NFS version 4.1 and later minor versions, the | In the case of NFS version 4.1 and later minor versions, the | |||
means of | means of | |||
trunking detection are as described in this document | trunking detection are as described in this document | |||
and are available | and are available to every client. Two network addresses | |||
to every client. Two network addresses | ||||
connected to the same server can always be used together | connected to the same server can always be used together | |||
to access a particular server | to access a particular server | |||
but cannot necessarily be used together | but cannot necessarily be used together | |||
to access a single session. See below for definitions | to access a single session. See below for definitions | |||
of the terms "server-trunkable" and "session-trunkable" | of the terms "server-trunkable" and "session-trunkable". | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
Trunking discovery is a process by which a client using one | Trunking discovery is a process by which a client using one | |||
network address can obtain other addresses that are connected | network address can obtain other addresses that are connected | |||
to the | to the same server. | |||
same server. | ||||
Typically, it builds on a trunking detection facility by providing | Typically, it builds on a trunking detection facility by providing | |||
one or more methods by which candidate addresses are made | one or more methods by which candidate addresses are made | |||
available to the client | available to the client, | |||
who can then use trunking detection to appropriately filter them. | who can then use trunking detection to appropriately filter them. | |||
<vspace blankLines="1"/> | </t> | |||
Despite the support for trunking detection there was no | <t> | |||
Despite the support for trunking detection, there was no | ||||
description of trunking discovery provided in | description of trunking discovery provided in | |||
RFC5661 <xref target="RFC5661"/>, making it necessary to provide | RFC 5661 <xref target="RFC5661" format="default"/>, making it necessary to provide | |||
those means in this document. | those means in this document. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ul> | |||
<t> | <t> | |||
The combination of a server network address and a particular | The combination of a server network address and a particular | |||
connection type to be used by a connection | connection type to be used by a connection | |||
is referred to as a "server endpoint". Although using different | is referred to as a "server endpoint". Although using different | |||
connection types may result in different ports being used, the | connection types may result in different ports being used, the | |||
use of different ports by multiple connections to the same | use of different ports by multiple connections to the same | |||
network address in such cases is not the essence of the distinction | network address in such cases is not the essence of the distinction | |||
between the two endpoints used. This is in contrast to the case | between the two endpoints used. This is in contrast to the case | |||
of port-specific endpoints, | of port-specific endpoints, | |||
in which the explicit specification of port numbers within network | in which the explicit specification of port numbers within network | |||
addresses is used to allow a single server node to support multiple | addresses is used to allow a single server node to support multiple | |||
NFS servers. | NFS servers. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
Two network addresses connected to the same server are said to | Two network addresses connected to the same server are said to | |||
be server-trunkable. Two such addresses support the use of | be server-trunkable. Two such addresses support the use of | |||
clientid ID trunking, as described in <xref target="Trunking"/>. | client ID trunking, as described in <xref target="Trunking" format="defau | |||
</t> | lt"/>. | |||
<t> | </t> | |||
<t> | ||||
Two network addresses connected to the same server such that | Two network addresses connected to the same server such that | |||
those addresses can be used to support a single common session | those addresses can be used to support a single common session | |||
are referred to as session-trunkable. Note that two addresses | are referred to as session-trunkable. Note that two addresses | |||
may be server-trunkable without being session-trunkable and that | may be server-trunkable without being session-trunkable, and that, | |||
when two connections of different connection types are made | when two connections of different connection types are made | |||
to the same network address and are based on a single file | to the same network address and are based on a single file | |||
system location entry | system location entry, they are always | |||
they are always | ||||
session-trunkable, independent of the connection type, as | session-trunkable, independent of the connection type, as | |||
specified by <xref target="Trunking"/>, since their derivation from | specified by <xref target="Trunking" format="default"/>, since their deri | |||
the same file system location entry together with the identity of | vation from | |||
their network addresses assures that both | the same file system location entry, together with the identity of | |||
connections are to the | their network addresses, assures that both connections are to the | |||
same server and will return server-owner information allowing | same server and will return server-owner information, allowing | |||
session trunking to be used. | session trunking to be used. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Terminology Related to File System Location" | <section anchor="SEC11-TERM-loc" numbered="true" toc="default"> | |||
anchor="SEC11-TERM-loc"> | <name>Terminology Related to File System Location</name> | |||
<t> | <t> | |||
Regarding terminology relating to the construction of multi-server | Regarding the terminology that relates to the construction of multi-server | |||
namespaces out of a set of local per-server namespaces: | namespaces out of a set of local per-server namespaces: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
Each server has a set of exported file systems which may be accessed | <li> | |||
Each server has a set of exported file systems that may be accessed | ||||
by NFSv4 clients. Typically, this is done by assigning each | by NFSv4 clients. Typically, this is done by assigning each | |||
file system a name within the pseudo-fs associated with the | file system a name within the pseudo-fs associated with the | |||
server, although the pseudo-fs may be dispensed with if there | server, although the pseudo-fs may be dispensed with if there | |||
is only a single exported file system. Each such file system | is only a single exported file system. Each such file system | |||
is part of the server's local namespace, and can be considered | is part of the server's local namespace, and can be considered | |||
as a file system instance within a larger multi-server | as a file system instance within a larger multi-server namespace. | |||
namespace. | </li> | |||
</t> | <li> | |||
<t> | ||||
The set of all exported file systems for a given server | The set of all exported file systems for a given server | |||
constitutes that server's local namespace. | constitutes that server's local namespace. | |||
</t> | </li> | |||
<t> | <li> | |||
In some cases, a server will have a namespace more extensive | In some cases, a server will have a namespace more extensive | |||
than its local namespace by using features associated with | than its local namespace by using features associated with | |||
attributes that provide file system location information. | attributes that provide file system location information. | |||
These features, | These features, | |||
which allow construction of a multi-server namespace, | which allow construction of a multi-server namespace, | |||
are all described in individual sections below and include | are all described in individual sections below and include | |||
referrals (described in <xref target="SEC11-USES-ref"/>), | referrals (<xref target="SEC11-USES-ref" format="default"/>), | |||
migration (described in <xref target="SEC11-USES-migr"/>), and | migration (<xref target="SEC11-USES-migr" format="default"/>), and | |||
replication (described in <xref target="SEC11-USES-repl"/>). | replication (<xref target="SEC11-USES-repl" format="default"/>). | |||
</t> | </li> | |||
<t> | <li> | |||
A file system present in a server's pseudo-fs may have multiple | A file system present in a server's pseudo-fs may have multiple | |||
file system instances on different servers associated with it. | file system instances on different servers associated with it. | |||
All such instances are considered replicas of one another. | All such instances are considered replicas of one another. | |||
Whether such replicas can be used simultaneously is discussed in | Whether such replicas can be used simultaneously is discussed in | |||
<xref target="SEC11-EFF-simul"/>, while the level of | <xref target="SEC11-EFF-simul" format="default"/>, while the level of | |||
co-ordination between them (important when switching | coordination between them (important when switching | |||
between them) is discussed in Sections | between them) is discussed in Sections | |||
<xref target="SEC11-EFF-fh" format="counter"/> | <xref target="SEC11-EFF-fh" format="counter"/> | |||
through <xref target="SEC11-EFF-data" format="counter"/> | through <xref target="SEC11-EFF-data" format="counter"/> below. | |||
below. | </li> | |||
<li> | ||||
</t> | ||||
<t> | ||||
When a file system is present in a server's pseudo-fs, but | When a file system is present in a server's pseudo-fs, but | |||
there is no corresponding local file system, it is said to | there is no corresponding local file system, it is said to | |||
be "absent". In such cases, all associated instances will | be "absent". In such cases, all associated instances will | |||
be accessed on other servers. | be accessed on other servers. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | Regarding the terminology that relates to attributes used in trunking | |||
Regarding terminology relating to attributes used in trunking | ||||
discovery and other multi-server namespace features: | discovery and other multi-server namespace features: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
File system location attributes include the fs_locations and | File system location attributes include the fs_locations and | |||
fs_locations_info attributes. | fs_locations_info attributes. | |||
</t> | </li> | |||
<t> | <li> | |||
File system location entries provide the individual | <t> | |||
file system locations | File system location entries provide the individual file system | |||
within the file system location attributes. | locations within the file system location attributes. | |||
Each such entry specifies a | Each such entry specifies a | |||
server, in the form of a host name or an address, and an fs name, | server, in the form of a hostname or an address, and an fs name, | |||
which designates the location of the file system within | which designates the location of the file system within | |||
the server's local namespace. A file system | the server's local namespace. A file system location entry designates a | |||
location entry designates a set | set | |||
of server endpoints to which the client may establish connections. | of server endpoints to which the client may establish connections. | |||
There may be multiple endpoints because a host name may map to | There may be multiple endpoints because a hostname may map to | |||
multiple network addresses and because multiple connection types | multiple network addresses and because multiple connection types | |||
may be | may be | |||
used to communicate with a single network address. However, | used to communicate with a single network address. However, | |||
except where an explicit port numbers are used to designate a set | except where explicit port numbers are used to designate a set | |||
of server within a single server node, all | of servers within a single server node, all | |||
such endpoints MUST designate a way of connecting to a single server. | such endpoints <bcp14>MUST</bcp14> designate a way of connecting to a sin | |||
gle server. | ||||
The exact form of the location entry varies with the | The exact form of the location entry varies with the | |||
particular file system location attribute used, as described in | particular file system location attribute used, as described in | |||
<xref target="SEC11-loc-attr"/>. | <xref target="SEC11-loc-attr" format="default"/>. | |||
<vspace blankLines='1'/> | </t> | |||
<t> | ||||
The network addresses used in file system location entries | The network addresses used in file system location entries | |||
typically appear without port number indications and are | typically appear without port number indications and are | |||
used to designate a server at one of the standard ports for NFS access, | used to designate a server at one of the standard ports for NFS access, | |||
e.g., 2049 for TCP, or 20049 for use with RPC-over-RDMA. Port | e.g., 2049 for TCP or 20049 for use with RPC-over-RDMA. Port | |||
numbers may be used | numbers may be used | |||
in file system location entries to designate servers (typically | in file system location entries to designate servers (typically | |||
user-level ones) accessed using other port numbers. In the case where | user-level ones) accessed using other port numbers. In the case where | |||
network addresses indicate trunking relationships, use of an explicit | network addresses indicate trunking relationships, the use of an explicit | |||
port number is inappropriate since trunking is a relationship between | port number is inappropriate since trunking is a relationship between | |||
network addresses. See <xref target="SEC11-USES-trunk"/> for | network addresses. See <xref target="SEC11-USES-trunk" format="default"/ > for | |||
details. | details. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
File system location elements are derived from | File system location elements are derived from | |||
location entries and each | location entries, and each | |||
describes a particular network access path, consisting of a network | describes a particular network access path consisting of a network | |||
address and a location within the server's local namespace. | address and a location within the server's local namespace. | |||
Such location elements need not appear | Such location elements need not appear | |||
within a file system location attribute, but the | within a file system location attribute, but the | |||
existence of each location element derives from a corresponding | existence of each location element derives from a corresponding | |||
location entry. When a | location entry. When a | |||
location entry specifies an IP address there is only a single | location entry specifies an IP address, there is only a single | |||
corresponding location element. File system location entries that | corresponding location element. File system location entries that | |||
contain a host name are resolved using DNS, and may result | contain a hostname are resolved using DNS, and may result | |||
in one or more location elements. All location elements | in one or more location elements. All location elements | |||
consist of a location address which includes the IP address of | consist of a location address that includes the IP address of | |||
an interface to a server and an fs name which is the location | an interface to a server and an fs name, which is the location | |||
of the file system within the server's local namespace. The fs name | of the file system within the server's local namespace. The fs name | |||
can be empty if the server has no pseudo-fs and only a single exported | can be empty if the server has no pseudo-fs and only a single exported | |||
file system at the root filehandle. | file system at the root filehandle. | |||
</t> | </li> | |||
<t> | <li> | |||
Two file system location elements are said to be | Two file system location elements are said to be | |||
server-trunkable if they | server-trunkable if they | |||
specify the same fs name and the location addresses are such | specify the same fs name and the location addresses are such | |||
that the location addresses are server-trunkable. When the | that the location addresses are server-trunkable. When the | |||
corresponding network paths are used, the client will always be | corresponding network paths are used, the client will always be | |||
able to use client ID trunking, but will only be able to use | able to use client ID trunking, but will only be able to use | |||
session trunking if the paths are also session-trunkable. | session trunking if the paths are also session-trunkable. | |||
</li> | ||||
</t> | <li> | |||
<t> | ||||
Two file system location elements are said to be session-trunkable | Two file system location elements are said to be session-trunkable | |||
if they | if they | |||
specify the same fs name and the location addresses are such | specify the same fs name and the location addresses are such | |||
that the location addresses are session-trunkable. When the | that the location addresses are session-trunkable. When the | |||
corresponding network paths are used, the client will be able to | corresponding network paths are used, the client will be able to | |||
able to use either client ID trunking or session trunking. | able to use either client ID trunking or session trunking. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Discussion of the term "replica" is complicated by the fact that | Discussion of the term "replica" is complicated by the fact that | |||
the term was used in RFC5661 <xref target="RFC5661"/>, with a meaning | the term was used in RFC 5661 <xref target="RFC5661" format="default"/> wi | |||
different from that in this document. In short, | th a meaning | |||
in <xref target="RFC5661"/> each replica is identified by a | different from that used in this document. In short, | |||
single network access path while, in the current document a set | in <xref target="RFC5661" format="default"/> each replica is identified by | |||
of network access paths which have server-trunkable network | a | |||
single network access path, while in the current document, a set | ||||
of network access paths that have server-trunkable network | ||||
addresses and the same root-relative file system pathname is | addresses and the same root-relative file system pathname is | |||
considered to be a single replica with multiple network access | considered to be a single replica with multiple network access | |||
paths. | paths. | |||
</t> | </t> | |||
<t> | <t> | |||
Each set of server-trunkable location elements defines a set of | Each set of server-trunkable location elements defines a set of | |||
available network access paths to a particular file system. | available network access paths to a particular file system. | |||
When there | When there | |||
are multiple such file systems, each of which contains the | are multiple such file systems, each of which containing the | |||
same data, these file systems are considered replicas | same data, these file systems are considered replicas | |||
of one another. Logically, such replication | of one another. Logically, such replication | |||
is symmetric, since the fs currently in use and an alternate fs | is symmetric, since the fs currently in use and an alternate fs | |||
are replicas of each other. Often, in other documents, the term | are replicas of each other. Often, in other documents, the term | |||
"replica" is not applied to the fs currently in use, despite the | "replica" is not applied to the fs currently in use, despite the | |||
fact that the replication relation is inherently symmetric. | fact that the replication relation is inherently symmetric. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section title="File System Location Attributes" | <section anchor="SEC11-loc-attr" numbered="true" toc="default"> | |||
anchor="SEC11-loc-attr"> | <name>File System Location Attributes</name> | |||
<t> | <t> | |||
NFSv4.1 contains attributes that provide information | NFSv4.1 contains attributes that provide information | |||
about how (i.e., at what network address and namespace position) | about how a given file system may be accessed | |||
a given file system may be accessed. As a result, file systems | (i.e., at what network address and namespace position). As a result, file | |||
systems | ||||
in the namespace of one server can be | in the namespace of one server can be | |||
associated with one or more instances of that | associated with one or more instances of that | |||
file system on other servers. These attributes contain file | file system on other servers. These attributes contain file | |||
system location | system location | |||
entries specifying a server address | entries specifying a server address | |||
target (either as a DNS name representing one or more IP | target (either as a DNS name representing one or more IP | |||
addresses or as a specific IP address) together with the pathname | addresses or as a specific IP address) together with the pathname | |||
of that file system within the associated single-server namespace. | of that file system within the associated single-server namespace. | |||
</t> | </t> | |||
<t> | <t> | |||
The fs_locations_info RECOMMENDED attribute | The fs_locations_info <bcp14>RECOMMENDED</bcp14> attribute | |||
allows specification of one or more file system instance locations | allows specification of one or more file system instance locations | |||
where the data corresponding to a given file | where the data corresponding to a given file | |||
system may be found. This attribute provides to the client, | system may be found. | |||
in addition to specification of file system instance locations, | In addition to the specification of file system instance locations, | |||
other helpful | this attribute provides helpful information to do the following: | |||
information such as: | </t> | |||
<list style='symbols'> | <ul spacing="normal"> | |||
<t> | <li> | |||
Information guiding choices among the various file system instances | Guide choices among the various file system instances | |||
provided (e.g., priority for use, writability, currency, etc.). | provided (e.g., priority for use, writability, currency, etc.). | |||
</t> | </li> | |||
<t> | <li> | |||
Help the client efficiently effect as seamless | ||||
Information to help the client efficiently effect as seamless | a transition as possible among multiple file system instances, | |||
a transition | when and if that should be necessary. | |||
as possible among multiple file system instances, when and if | </li> | |||
that should be necessary. | <li> | |||
</t> | Guide the selection of the appropriate | |||
<t> | ||||
Information helping to guide the selection of the appropriate | ||||
connection type to be used when establishing a connection. | connection type to be used when establishing a connection. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
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 with the | location entry: the fls_server field designates the server, | |||
fls_server field designating the server, with the location pathname | and the fl_rootpath field of the encompassing fs_locations_item4 | |||
within | gives the location pathname within the server's pseudo-fs. | |||
the server's pseudo-fs given by the fl_rootpath field of the | </t> | |||
encompassing fs_locations_item4. | <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 | NFSv4.1. This attribute only allows specification of the file system | |||
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 SHOULD make this attribute available | system may be found. Servers <bcp14>SHOULD</bcp14> make this attribute a vailable | |||
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, as it provides more information. | fs_locations_info is preferable because it provides more information. | |||
</t> | </t> | |||
<t> | <t> | |||
Within the fs_location attribute, each fs_location4 contains a | Within the fs_locations attribute, each fs_location4 contains a | |||
file system location entry with the server field designating | file system location entry with the server field designating | |||
the server and | the server and the rootpath field giving the location pathname | |||
the rootpath field giving the location pathname within the server's | within the server's pseudo-fs. | |||
pseudo-fs. | </t> | |||
</t> | </section> | |||
</section> | <section anchor="presence_or_absence" numbered="true" toc="default"> | |||
<section title="File System Presence or Absence" | <name>File System Presence or Absence</name> | |||
anchor="presence_or_absence"> | <t> | |||
<t> | ||||
A given location in an NFSv4.1 namespace (typically but not necessarily | A given location in an NFSv4.1 namespace (typically but not necessarily | |||
a multi-server namespace) can have a number of file system instance | a multi-server namespace) can have a number of file system instance | |||
locations | locations | |||
associated with it (via the fs_locations or fs_locations_info | associated with it (via the fs_locations or fs_locations_info | |||
attribute). There may also be an actual current file system at | attribute). There may also be an actual current file system at | |||
that location, accessible via normal namespace operations (e.g., | that location, accessible via normal namespace operations (e.g., | |||
LOOKUP). In this case, the file system is said to be | LOOKUP). In this case, the file system is said to be | |||
"present" at that position in the namespace, and clients will | "present" at that position in the namespace, and clients will | |||
typically use it, reserving use of additional locations | typically use it, reserving use of additional locations | |||
specified via the location-related attributes to situations in | specified via the location-related attributes to situations in | |||
which the principal location is no longer available. | which the principal location is no longer available. | |||
</t> | </t> | |||
<t> | <t> | |||
When there is no actual file system at the namespace location | When there is no actual file system at the namespace location | |||
in question, the file system is said to be "absent". An absent | in question, the file system is said to be "absent". An absent | |||
file system contains no files or directories other than the | file system contains no files or directories other than the | |||
root. Any reference to it, except | root. Any reference to it, except | |||
to access a small set of attributes useful in determining | to access a small set of attributes useful in determining | |||
alternate locations, will result in an error, NFS4ERR_MOVED. | alternate locations, will result in an error, NFS4ERR_MOVED. | |||
Note that if the server ever returns the error NFS4ERR_MOVED, | Note that if the server ever returns the error NFS4ERR_MOVED, | |||
it MUST support the fs_locations | it <bcp14>MUST</bcp14> support the fs_locations | |||
attribute and SHOULD support the fs_locations_info and fs_status | attribute and <bcp14>SHOULD</bcp14> support the fs_locations_info and fs_s | |||
tatus | ||||
attributes. | attributes. | |||
</t> | </t> | |||
<t> | <t> | |||
While the error name suggests that we have a case of a file system | While the error name suggests that we have a case of a file system | |||
that once was present, and has only become absent later, this is | that once was present, and has only become absent later, this is | |||
only one possibility. A position in the namespace may be permanently | only one possibility. A position in the namespace may be permanently | |||
absent with the set of file system(s) designated by the location | absent with the set of file system(s) designated by the location | |||
attributes being the only realization. | attributes being the only realization. | |||
The name NFS4ERR_MOVED reflects an earlier, | The name NFS4ERR_MOVED reflects an earlier, | |||
more limited conception of its function, but this error will be | more limited conception of its function, but this error will be | |||
returned whenever the referenced file system is absent, whether it | returned whenever the referenced file system is absent, whether it | |||
has moved or not. | has moved or not. | |||
</t> | </t> | |||
<t> | <t> | |||
Except in the case of GETATTR-type operations (to be discussed | Except in the case of GETATTR-type operations (to be discussed | |||
later), when the | later), when the | |||
current filehandle at the start of an operation is within an | current filehandle at the start of an operation is within an | |||
absent file system, that operation is not performed and the error | absent file system, that operation is not performed and the error | |||
NFS4ERR_MOVED is returned, to indicate that the file system is | NFS4ERR_MOVED is returned, to indicate that the file system is | |||
absent on the current server. | absent on the current server. | |||
</t> | </t> | |||
<t> | <t> | |||
Because a GETFH cannot succeed if the current filehandle is | Because a GETFH cannot succeed if the current filehandle is | |||
within an absent file system, filehandles within an absent | within an absent file system, filehandles within an absent | |||
file system cannot be transferred to the client. When a | file system cannot be transferred to the client. When a | |||
client does have filehandles within an absent file system, it | client does have filehandles within an absent file system, it | |||
is the result of obtaining them when the file system was | is the result of obtaining them when the file system was | |||
present, and having the file system become | present, and having the file system become | |||
absent subsequently. | absent subsequently. | |||
</t> | </t> | |||
<t> | <t> | |||
It should be noted that because the check for the current | It should be noted that because the check for the current | |||
filehandle being within an absent file system happens at the | filehandle being within an absent file system happens at the | |||
start of every operation, operations that change the current | start of every operation, operations that change the current | |||
filehandle so that it is within an absent file system will not | filehandle so that it is within an absent file system will not | |||
result in an error. This allows such combinations as | result in an error. This allows such combinations as | |||
PUTFH-GETATTR and LOOKUP-GETATTR to be used to get attribute | PUTFH-GETATTR and LOOKUP-GETATTR to be used to get attribute | |||
information, particularly location attribute information, | information, particularly location attribute information, | |||
as discussed below. | as discussed below. | |||
</t> | </t> | |||
<t> | <t> | |||
The RECOMMENDED file system attribute fs_status | The <bcp14>RECOMMENDED</bcp14> file system attribute fs_status | |||
can be used to interrogate the present/absent status of a | can be used to interrogate the present/absent status of a | |||
given file system. | given file system. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Getting Attributes for an Absent File System" | <section anchor="absent_fs_attributes" numbered="true" toc="default"> | |||
anchor="absent_fs_attributes" > | <name>Getting Attributes for an Absent File System</name> | |||
<t> | <t> | |||
When a file system is absent, most attributes are not available, | When a file system is absent, most attributes are not available, | |||
but it is necessary to allow the client access to the small | but it is necessary to allow the client access to the small | |||
set of attributes that are available, and most particularly | set of attributes that are available, and most particularly | |||
those that give information about the correct current locations | those that give information about the correct current locations | |||
for this file system: fs_locations and fs_locations_info. | for this file system: fs_locations and fs_locations_info. | |||
</t> | </t> | |||
<section anchor="absent_getattr" | <section anchor="absent_getattr" numbered="true" toc="default"> | |||
title="GETATTR within an Absent File System"> | <name>GETATTR within an Absent File System</name> | |||
<t> | <t> | |||
As mentioned above, an exception is made for GETATTR in that | As mentioned above, an exception is made for GETATTR in that | |||
attributes may be obtained for a filehandle within an absent | attributes may be obtained for a filehandle within an absent | |||
file system. This exception only applies if the attribute | file system. This exception only applies if the attribute | |||
mask contains at least one attribute bit that indicates the | mask contains at least one attribute bit that indicates the | |||
client is interested in a result regarding an absent file | client is interested in a result regarding an absent file | |||
system: fs_locations, fs_locations_info, or fs_status. | system: fs_locations, fs_locations_info, or fs_status. | |||
If none of these attributes | If none of these attributes | |||
is requested, GETATTR will result in an NFS4ERR_MOVED error. | is requested, GETATTR will result in an NFS4ERR_MOVED error. | |||
</t> | </t> | |||
<t> | <t> | |||
When a GETATTR is done on an absent file system, the set of | When a GETATTR is done on an absent file system, the set of | |||
supported attributes is very limited. Many attributes, including | supported attributes is very limited. Many attributes, including | |||
those that are normally REQUIRED, will not be available on an | those that are normally <bcp14>REQUIRED</bcp14>, will not be available o n an | |||
absent file system. In addition to the attributes mentioned | absent file system. In addition to the attributes mentioned | |||
above (fs_locations, fs_locations_info, fs_status), the following | above (fs_locations, fs_locations_info, fs_status), the following | |||
attributes SHOULD be available on absent file systems. In the | attributes <bcp14>SHOULD</bcp14> be available on absent file systems. I | |||
case of RECOMMENDED attributes, they should be available at | n the | |||
case of <bcp14>RECOMMENDED</bcp14> attributes, they should be available | ||||
at | ||||
least to the same degree that they are available on present file systems . | least to the same degree that they are available on present file systems . | |||
</t> | </t> | |||
<t> | <dl newline="false" spacing="normal"> | |||
<list style='hanging'> | <dt>change_policy:</dt> | |||
<t hangText="change_policy:"> | <dd> | |||
This attribute is useful for absent file systems | This attribute is useful for absent file systems | |||
and can be helpful in summarizing to the client when any | and can be helpful in summarizing to the client when any | |||
of the location-related attributes change. | of the location-related attributes change. | |||
</t> | </dd> | |||
<t hangText="fsid:"> | <dt>fsid:</dt> | |||
<dd> | ||||
This attribute should be provided so that the client | This attribute should be provided so that the client | |||
can determine file system boundaries, including, in | can determine file system boundaries, including, in | |||
particular, the boundary between present and absent file | particular, the boundary between present and absent file | |||
systems. This value must be different from any other fsid | systems. This value must be different from any other fsid | |||
on the current server and need have no particular relationship | on the current server and need have no particular relationship | |||
to fsids on any particular destination to which the client | to fsids on any particular destination to which the client | |||
might be directed. | might be directed. | |||
</t> | </dd> | |||
<t hangText="mounted_on_fileid:"> | <dt>mounted_on_fileid:</dt> | |||
<dd> | ||||
For objects at the top of an absent | For objects at the top of an absent | |||
file system, this attribute needs to be available. Since | file system, this attribute needs to be available. Since | |||
the fileid is within the present parent file | the fileid is within the present parent file | |||
system, there should be no need to reference the absent file | system, there should be no need to reference the absent file | |||
system to provide this information. | system to provide this information. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | <t> | |||
<t> | Other attributes <bcp14>SHOULD NOT</bcp14> be made available for absent | |||
Other attributes SHOULD NOT be made available for absent file | file | |||
systems, even when it is possible to provide them. The server | systems, even when it is possible to provide them. The server | |||
should not assume that more information is always better and | should not assume that more information is always better and | |||
should avoid gratuitously providing additional information. | should avoid gratuitously providing additional information. | |||
</t> | </t> | |||
<t> | <t> | |||
When a GETATTR operation includes a bit mask for one of the | When a GETATTR operation includes a bit mask for one of the | |||
attributes fs_locations, fs_locations_info, or fs_status, but | attributes fs_locations, fs_locations_info, or fs_status, but | |||
where the bit mask includes attributes that are not supported, | where the bit mask includes attributes that are not supported, | |||
GETATTR will not return an error, but will return the mask | GETATTR will not return an error, but will return the mask | |||
of the actual attributes supported with the results. | of the actual attributes supported with the results. | |||
</t> | </t> | |||
<t> | <t> | |||
Handling of VERIFY/NVERIFY is similar to GETATTR in that if | Handling of VERIFY/NVERIFY is similar to GETATTR in that if | |||
the attribute mask does not include fs_locations, fs_locations_info, | the attribute mask does not include fs_locations, fs_locations_info, | |||
or fs_status, the error NFS4ERR_MOVED will result. It differs in | or fs_status, the error NFS4ERR_MOVED will result. It differs in | |||
that any appearance in the attribute mask of an attribute not | that any appearance in the attribute mask of an attribute not | |||
supported for an absent file system (and note that this will | supported for an absent file system (and note that this will | |||
include some normally REQUIRED attributes) will also cause | include some normally <bcp14>REQUIRED</bcp14> attributes) will also caus e | |||
an NFS4ERR_MOVED result. | an NFS4ERR_MOVED result. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="absent_readdir" | <section anchor="absent_readdir" numbered="true" toc="default"> | |||
title="READDIR and Absent File Systems"> | <name>READDIR and Absent File Systems</name> | |||
<t> | <t> | |||
A READDIR performed when the current filehandle is within an | A READDIR performed when the current filehandle is within an | |||
absent file system will result in an NFS4ERR_MOVED error, | absent file system will result in an NFS4ERR_MOVED error, | |||
since, unlike the case of GETATTR, no such exception is | since, unlike the case of GETATTR, no such exception is | |||
made for READDIR. | made for READDIR. | |||
</t> | </t> | |||
<t> | <t> | |||
Attributes for an absent file system may be fetched via a | Attributes for an absent file system may be fetched via a | |||
READDIR for a directory in a present file system, when that | READDIR for a directory in a present file system, when that | |||
directory contains the root directories of one or more absent | directory contains the root directories of one or more absent | |||
file systems. In this case, the handling is as follows: | file systems. In this case, the handling is as follows: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
If the attribute set requested includes one of the attributes | If the attribute set requested includes one of the attributes | |||
fs_locations, fs_locations_info, or fs_status, then fetching of | fs_locations, fs_locations_info, or fs_status, then fetching of | |||
attributes proceeds normally and no NFS4ERR_MOVED indication | attributes proceeds normally and no NFS4ERR_MOVED indication | |||
is returned, even when the rdattr_error attribute is | is returned, even when the rdattr_error attribute is | |||
requested. | requested. | |||
</t> | </li> | |||
<t> | <li> | |||
If the attribute set requested does not include one of the | If the attribute set requested does not include one of the | |||
attributes | attributes | |||
fs_locations, fs_locations_info, or fs_status, then if the | fs_locations, fs_locations_info, or fs_status, then if the | |||
rdattr_error attribute is requested, each directory entry for | rdattr_error attribute is requested, each directory entry for | |||
the root of an absent file system will report | the root of an absent file system will report | |||
NFS4ERR_MOVED as the value of the rdattr_error attribute. | NFS4ERR_MOVED as the value of the rdattr_error attribute. | |||
</t> | </li> | |||
<t> | <li> | |||
If the attribute set requested does not include any of the | If the attribute set requested does not include any of the | |||
attributes fs_locations, fs_locations_info, fs_status, or | attributes fs_locations, fs_locations_info, fs_status, or | |||
rdattr_error, then the occurrence of the root of an absent | rdattr_error, then the occurrence of the root of an absent | |||
file system within the directory will result in the | file system within the directory will result in the | |||
READDIR failing with an NFS4ERR_MOVED error. | READDIR failing with an NFS4ERR_MOVED error. | |||
</t> | </li> | |||
<t> | <li> | |||
The unavailability of an attribute because of a file system's | The unavailability of an attribute because of a file system's | |||
absence, even one that is ordinarily REQUIRED, does not result | absence, even one that is ordinarily <bcp14>REQUIRED</bcp14>, does not result | |||
in any error indication. The set of attributes returned for | in any error indication. The set of attributes returned for | |||
the root directory of the absent file system in that case is | the root directory of the absent file system in that case is | |||
simply restricted to those actually available. | simply restricted to those actually available. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="SEC11-USES" numbered="true" toc="default"> | |||
<section title="Uses of File System Location Information" | <name>Uses of File System Location Information</name> | |||
anchor="SEC11-USES"> | <t> | |||
<t> | ||||
The file system location attributes | The file system location attributes | |||
(i.e. fs_locations and fs_locations_info), | (i.e., fs_locations and fs_locations_info), | |||
together with the possibility of absent file systems, provide | together with the possibility of absent file systems, provide | |||
a number of important facilities in providing reliable, manageable, | a number of important facilities for reliable, manageable, | |||
and scalable data access. | and scalable data access. | |||
</t> | </t> | |||
<t> | <t> | |||
When a file system is present, these attributes can provide | When a file system is present, these attributes can provide | |||
<list style="symbols"> | the following: | |||
<t> | </t> | |||
The locations of alternative replicas, to be used to access the | <ul spacing="normal"> | |||
same data in the event of server failures, | <li> | |||
communications problems, | The locations of alternative replicas to be used to access the | |||
same data in the event of server failures, communications problems, | ||||
or other difficulties that make continued access to the current | or other difficulties that make continued access to the current | |||
replica impossible or otherwise impractical. Provision and | replica impossible or otherwise impractical. Provisioning and | |||
use of | use of such alternate replicas is referred to as "replication" | |||
such alternate replicas is referred to as "replication" | ||||
and is discussed in | and is discussed in | |||
<xref target="SEC11-USES-repl"/> below. | <xref target="SEC11-USES-repl" format="default"/> below. | |||
</t> | </li> | |||
<t> | <li> | |||
The network address(es) to be used to access the current file | The network address(es) to be used to access the current file | |||
system instance or replicas of it. | system instance or replicas of it. Client use of this information is | |||
Client use of this information is | discussed in <xref target="SEC11-USES-trunk" format="default"/> below. | |||
discussed in | </li> | |||
<xref target="SEC11-USES-trunk"/> below. | </ul> | |||
</t> | <t> | |||
</list> | ||||
</t> | ||||
<t> | ||||
Under some circumstances, multiple replicas | Under some circumstances, multiple replicas | |||
may be used simultaneously to provide higher-performance | may be used simultaneously to provide higher-performance | |||
access to the file system in question, although the lack of state | access to the file system in question, although the lack of state | |||
sharing between servers may be an impediment to such use. | sharing between servers may be an impediment to such use. | |||
</t> | </t> | |||
<t> | <t> | |||
When a file system is present and becomes absent, clients can be | When a file system is present but becomes absent, clients can be | |||
given the opportunity to have continued access to their data, | given the opportunity to have continued access to their data | |||
using a different replica. In this case, a continued attempt | using a different replica. In this case, a continued attempt | |||
to use the data in the now-absent file system will result | to use the data in the now-absent file system will result | |||
in an NFS4ERR_MOVED error and, at that point, the successor | in an NFS4ERR_MOVED error, and then the successor | |||
replica or set of possible replica choices | replica or set of possible replica choices | |||
can be fetched and used to continue access. Transfer of access | can be fetched and used to continue access. Transfer of access | |||
to the new replica location is referred to as | to the new replica location is referred to as | |||
"migration", and is discussed in | "migration" and is discussed in | |||
<xref target="SEC11-USES-repl"/> below. | <xref target="SEC11-USES-repl" format="default"/> below. | |||
</t> | ||||
</t> | <t> | |||
<t> | When a file system is currently absent, specification | |||
Where a file system is currently absent, specification | ||||
of file system location provides a means by which file systems | of file system location provides a means by which file systems | |||
located on one server can be associated with a namespace | located on one server can be associated with a namespace | |||
defined by another server, thus allowing a general multi-server | defined by another server, thus allowing a general multi-server | |||
namespace facility. A designation of such a remote instance, in | namespace facility. A designation of such a remote instance, in | |||
place of a file system not previously present, is called | place of a file system not previously present, is called | |||
a "pure referral" and is discussed in | a "pure referral" and is discussed in | |||
<xref target="SEC11-USES-ref"/> below. | <xref target="SEC11-USES-ref" format="default"/> below. | |||
</t> | </t> | |||
<t> | <t> | |||
Because client support for attributes related to file | Because client support for attributes related to file | |||
system location is | system location is | |||
OPTIONAL, a server may choose to take action | <bcp14>OPTIONAL</bcp14>, a server may choose to take action | |||
to hide migration and referral events from such clients, by | to hide migration and referral events from such clients, by | |||
acting as a proxy, for example. The server can determine | acting as a proxy, for example. The server can determine | |||
the presence of client support from the arguments of the | the presence of client support from the arguments of the | |||
EXCHANGE_ID operation (see | EXCHANGE_ID operation (see | |||
<xref target="OP_EXCHANGE_ID_DESCRIPTION" />). | <xref target="OP_EXCHANGE_ID_DESCRIPTION" format="default"/>). | |||
</t> | </t> | |||
<section title="Combining Multiple Uses in a Single Attribute" | <section anchor="SEC11-USES-mult" numbered="true" toc="default"> | |||
anchor="SEC11-USES-mult"> | <name>Combining Multiple Uses in a Single Attribute</name> | |||
<t> | <t> | |||
A file system location attribute will sometimes contain information | A file system location attribute will sometimes contain information | |||
relating to the location of multiple replicas which may | relating to the location of multiple replicas, which may | |||
be used in different ways. | be used in different ways: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
File system location entries that relate to the file system instance | File system location entries that relate to the file system instance | |||
currently in | currently in | |||
use provide trunking information, allowing the client to | use provide trunking information, allowing the client to | |||
find additional network addresses by which the instance may be | find additional network addresses by which the instance may be | |||
accessed. | accessed. | |||
</t> | </li> | |||
<t> | <li> | |||
File system location entries that provide information about | File system location entries that provide information about | |||
replicas to which access is to | replicas to which access is to be transferred. | |||
be transferred. | </li> | |||
</t> | <li> | |||
<t> | ||||
Other file system location entries that relate to replicas | Other file system location entries that relate to replicas | |||
that are available to | that are available to | |||
use in the event that access to the current replica becomes | use in the event that access to the current replica becomes | |||
unsatisfactory. | unsatisfactory. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | In order to simplify client handling and to allow the best choice | |||
In order to simplify client handling and allow the best choice | ||||
of replicas to access, the server should adhere to the following | of replicas to access, the server should adhere to the following | |||
guidelines. | guidelines: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
All file system location entries that relate to a | All file system location entries that relate to a | |||
single file system instance | single file system instance should be adjacent. | |||
should be | </li> | |||
adjacent. | <li> | |||
</t> | ||||
<t> | ||||
File system location entries that relate to the instance | File system location entries that relate to the instance | |||
currently in use | currently in use should appear first. | |||
should appear first. | </li> | |||
</t> | <li> | |||
<t> | ||||
File system location entries that relate to replica(s) | File system location entries that relate to replica(s) | |||
to which migration | to which migration | |||
is occurring should appear before replicas which are available | is occurring should appear before replicas that are available | |||
for later use if the current replica should become inaccessible. | for later use if the current replica should become inaccessible. | |||
</li> | ||||
</t> | </ul> | |||
</list> | </section> | |||
</t> | <section anchor="SEC11-USES-trunk" numbered="true" toc="default"> | |||
</section> | <name>File System Location Attributes and Trunking</name> | |||
<section title="File System Location Attributes and Trunking" | <t> | |||
anchor="SEC11-USES-trunk"> | ||||
<t> | ||||
Trunking is the use of multiple connections between a client and | Trunking is the use of multiple connections between a client and | |||
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: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<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. | |||
</t> | </li> | |||
<t> | <li> | |||
The client | The client may fetch the file system location attribute for the | |||
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. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | When the client fetches a location attribute | |||
It should be noted that the client, when it fetches a location | for a file system, it should be noted that the client may encounter mul | |||
attribute for a file system, may encounter multiple entries for | tiple entries for a number of | |||
a number of reasons, so that, when determining trunking information, | reasons, such that when it determines trunking information, it may | |||
it may have to bypass addresses not trunkable with one already | need | |||
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> | |||
Location entries used to discover candidate addresses for | Location entries used to discover candidate addresses for | |||
use in trunking | use in trunking are subject to change, as discussed in | |||
are subject to change, as discussed in | <xref target="SEC11-USES-changes" format="default"/> below. | |||
<xref target="SEC11-USES-changes"/> below. | ||||
The client may respond to | The client may respond to | |||
such changes by using additional addresses once they are | such changes by using additional addresses once they are | |||
verified or by ceasing to use | verified or by ceasing to use | |||
existing ones. The server can force the client to cease using | existing ones. The server can force the client to cease using | |||
an address by returning NFS4ERR_MOVED when that address is used to | an address by returning NFS4ERR_MOVED when that address is used to | |||
access a file system. This allows a transfer of client access | access a file system. This allows a transfer of client access | |||
which is similar to | that is similar to migration, although the same file system instance | |||
migration, although the same file system instance | ||||
is accessed throughout. | is accessed throughout. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="File System Location Attributes and Connection Type Selectio | <section anchor="SEC11-USES-types" numbered="true" toc="default"> | |||
n" | <name>File System Location Attributes and Connection Type Selection</n | |||
anchor="SEC11-USES-types"> | ame> | |||
<t> | ||||
<t> | ||||
Because of the need to support multiple types of connections, | Because of the need to support multiple types of connections, | |||
clients face | clients face | |||
the issue of determining the proper connection type to use | the issue of determining the proper connection type to use | |||
when establishing | when establishing | |||
a connection to a given server network address. In some cases, | a connection to a given server network address. In some cases, | |||
this issue can be addressed through the use of the connection | this issue can be addressed through the use of the connection | |||
"step-up" facility described in | "step-up" facility described in | |||
<xref target="OP_CREATE_SESSION"/>. However, | <xref target="OP_CREATE_SESSION" format="default"/>. However, | |||
because there are cases is which that facility is not available, | because there are cases in which that facility is not available, | |||
the client may have to choose a connection type with no | the client may have to choose a connection type with no | |||
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 | information made available in this regard. The fs_locations attribute pro | |||
available in this regard. Fs_locations provides no information | vides 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 | the one preferred by the client is successfully established. | |||
by the client is successfully established. | </t> | |||
</t> | <t> | |||
<t> | The fs_locations_info attribute includes the FSLI4TF_RDMA flag, | |||
Fs_locations_info includes a flag, FSLI4TF_RDMA, which, when | which is convenient for a client wishing to use RDMA. When this | |||
set indicates that RPC-over-RDMA support is available using | flag is set, it indicates that RPC-over-RDMA support is available | |||
the specified location entry, by "stepping up" an existing | using the specified location entry. A client can establish a TCP | |||
TCP connection to include support for RDMA operation. This flag | connection and then convert that connection to use RDMA by using | |||
makes it convenient for a client wishing to use RDMA. When | the step-up facility. | |||
this flag is set, it can | </t> | |||
establish a TCP connection and then convert that connection | <t> | |||
to use RDMA by using the step-up facility. | ||||
</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> | |||
</section> | ||||
</section> | <section anchor="SEC11-USES-repl" numbered="true" toc="default"> | |||
<section title="File System Replication" | <name>File System Replication</name> | |||
anchor="SEC11-USES-repl"> | <t> | |||
<t> | ||||
The fs_locations and fs_locations_info attributes provide | The fs_locations and fs_locations_info attributes provide | |||
alternative file system locations, to be used to access data in place | alternative file system locations, to be used to access data in place | |||
of or in addition to | of or in addition to | |||
the current file system instance. On first access to a | the current file system instance. On first access to a | |||
file system, the client should obtain the set | file system, the client should obtain the set | |||
of alternate locations by interrogating the fs_locations or | of alternate locations by interrogating the fs_locations or | |||
fs_locations_info attribute, with the latter being preferred. | fs_locations_info attribute, with the latter being preferred. | |||
</t> | </t> | |||
<t> | <t> | |||
In the event that the occurrence of server failures, communications | In the event that the occurrence of server failures, communications | |||
problems, | problems, | |||
or other difficulties make continued access to the current | or other difficulties make continued access to the current | |||
file system impossible or otherwise impractical, the client | file system impossible or otherwise impractical, the client | |||
can use the alternate locations as a way to get continued | can use the alternate locations as a way to get continued | |||
access to its data. | access to its data. | |||
</t> | </t> | |||
<t> | <t> | |||
The alternate locations may be physical replicas of the | The alternate locations may be physical replicas of the | |||
(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 | they may provide for the use of various forms of server | |||
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 | can be represented within the fs_locations and fs_locations_info | |||
within the fs_locations and fs_locations_info attributes | attributes, and how the client deals with file system transition | |||
and how the client deals with | issues will be discussed in detail in later sections. | |||
file system transition issues will be discussed in detail in | </t> | |||
later sections. | <t> | |||
</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, making it necessary that clients using replication | by the protocol, which makes it necessary for clients using replication | |||
to switch among replicas undergoing change 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 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 title="File System Trunking Presented as Replication" | <name>File System Trunking Presented as Replication</name> | |||
anchor="SEC11-USES-repl-trunk"> | <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: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The two file system locations (i.e., the one on which the | The two file system locations (i.e., the one on which the | |||
location attribute is obtained and the one specified in the | location attribute is obtained and the one specified in the | |||
file system location entry) designate the same locations within | file system location entry) designate the same locations within | |||
their respective single-server namespaces. | their respective single-server namespaces. | |||
</t> | </li> | |||
<t> | <li> | |||
The two server network addresses (i.e., the one being used to | The two server network addresses (i.e., the one being used to | |||
obtain | obtain the location attribute and the one specified in the file syste | |||
the location attribute and the one specified in the file system | m | |||
location entry) designate the same server (as indicated by the | location entry) designate the same server (as indicated by the | |||
same value of the so_major_id field of the eir_server_owner field | same value of the so_major_id field of the eir_server_owner field | |||
returned in response to EXCHANGE_ID). | returned in response to EXCHANGE_ID). | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
When these conditions hold, operations using both access paths are | When these conditions hold, operations using both access paths are | |||
generally trunked, although, when the attribute fs_locations_info | generally trunked, although trunking may be disallowed when the | |||
is used, trunking may be disallowed: | attribute fs_locations_info is used: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<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. | |||
<vspace blankLines="1"/> | </t> | |||
In this case the two paths can be used serially with | <t> | |||
no transition activity required on the part of the client. In | In this case, the two paths can be used serially with no | |||
this case, any transition between access paths is transparent, | transition activity required on the part of the client, and any | |||
and the client, in transferring access from one to the other, is | transition between access paths is transparent. In transferring | |||
acting as it would in the event that communication is interrupted, | access from one to the other, the client acts as if communication | |||
with a new connection and possibly a new session being established | were interrupted, establishing a new connection and possibly a | |||
to continue access to the same file system. | new session to continue access to the same file system. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
Note that for two such location entries, any information within | Note that for two such location entries, any information within | |||
the fs_locations_info attribute that indicates the need for special | the fs_locations_info attribute that indicates the need for special | |||
transition activity, i.e., the appearance of the two file system | transition activity, i.e., the appearance of the two file system | |||
location entries with different handle, fileid, write-verifier, | location entries with different handle, fileid, write-verifier, | |||
change, and readdir classes, indicates a serious problem. The | change, and readdir classes, indicates a serious problem. The | |||
client, if it allows transition to the file system instance at | client, if it allows transition to the file system instance at | |||
all, must not treat any transition as a transparent one. | all, must not treat any transition as a transparent one. | |||
The server SHOULD NOT indicate that these two entries (for the | The server <bcp14>SHOULD NOT</bcp14> indicate that these two entries (for the | |||
same file system on the same server) belong to | same file system on the same server) belong to | |||
different handle, fileid, write-verifier, change, and readdir | different handle, fileid, write-verifier, change, and readdir | |||
classes, whether or not the two entries are shown belonging to | classes, whether or not the two entries are shown belonging to | |||
the same simultaneous-use class. | the same simultaneous-use class. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | These situations were recognized by <xref target="RFC5661" format="def | |||
These situations were recognized by <xref target="RFC5661"/>, | ault"/>, | |||
even though | even though that document made no explicit mention of trunking: | |||
that document made no explicit mention of trunking. | </t> | |||
<list style="symbols"> | <ul spacing="normal"> | |||
<t> | <li> | |||
It treated the situation that we describe as trunking as one | It treated the situation that we describe as trunking as one | |||
of simultaneous use of two distinct file system instances, | of simultaneous use of two distinct file system instances, | |||
even though, in the explanatory framework now used to | even though, in the explanatory framework now used to | |||
describe the situation, the case is one in which a single file | describe the situation, the case is one in which a single file | |||
system is accessed by two different trunked addresses. | system is accessed by two different trunked addresses. | |||
</t> | </li> | |||
<t> | <li> | |||
It treated the situation in which two paths are to be used | It treated the situation in which two paths are to be used | |||
serially as a special sort of "transparent transition". however, | serially as a special sort of "transparent transition". However, | |||
in the descriptive framework now used to categorize transition | in the descriptive framework now used to categorize transition | |||
situations, this is considered a case of a "network endpoint | situations, this is considered a case of a "network endpoint | |||
transition" | transition" (see <xref target="SEC11-trans-oview" format="default"/>) | |||
(see <xref target="SEC11-trans-oview"/>). | . | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="SEC11-USES-migr" numbered="true" toc="default"> | |||
<section title="File System Migration" | <name>File System Migration</name> | |||
anchor="SEC11-USES-migr"> | <t> | |||
<t> | ||||
When a file system is present and becomes inaccessible using the | When a file system is present and becomes inaccessible using the | |||
current access path, the NFSv4.1 | current access path, the NFSv4.1 protocol provides a means by | |||
protocol provides a means by which clients can be given the | which clients can be given the opportunity to have continued access to t | |||
opportunity to have continued access to their data. This may | heir data. | |||
involve use of a different access path to the existing replica or | This may involve using a different access path to the existing replica o | |||
by providing a path to a different replica. The new access path or | r | |||
the location of the new replica is specified | providing a path to a different replica. The new access path or | |||
by a file system | the location of the new replica is specified by a file system | |||
location attribute. | location attribute. The ensuing migration of access includes | |||
The ensuing migration of access includes | the ability to retain locks across the transition. Depending on circumst | |||
the ability | ances, | |||
to retain locks across the transition. Depending on circumstances, | ||||
this can involve: | this can involve: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The continued use of the existing clientid when accessing | The continued use of the existing clientid when accessing | |||
the current | the current replica using a new access path. | |||
replica using a new access path. | </li> | |||
</t> | <li> | |||
<t> | ||||
Use of lock reclaim, taking advantage of a per-fs grace period. | Use of lock reclaim, taking advantage of a per-fs grace period. | |||
</t> | </li> | |||
<t> | <li> | |||
Use of Transparent State Migration. | Use of Transparent State Migration. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Typically, a client will be | Typically, a client will be | |||
accessing the file system in question, get an NFS4ERR_MOVED | accessing the file system in question, get an NFS4ERR_MOVED | |||
error, and then use a file system location attribute | error, and then use a file system location attribute | |||
to determine the new access path for the data. When | to determine the new access path for the data. When | |||
fs_locations_info is used, additional information will be | fs_locations_info is used, additional information will be | |||
available that will define the nature of the client's | available that will define the nature of the client's | |||
handling of the transition to a new server. | handling of the transition to a new server. | |||
</t> | </t> | |||
<t> | <t> | |||
In most instances, servers will choose to migrate all clients using | In most instances, servers will choose to migrate all clients using | |||
a particular file system to a successor replica at the same time | a particular file system to a successor replica at the same time | |||
to avoid cases in which different clients are updating different | to avoid cases in which different clients are updating different | |||
replicas. However migration of individual client can be helpful | replicas. However, migration of an individual client can be helpful | |||
in providing load balancing, as long as the replicas in question | in providing load balancing, as long as the replicas in question | |||
are such that they represent the same data as described in | are such that they represent the same data as described in | |||
<xref target="SEC11-EFF-data"/>. | <xref target="SEC11-EFF-data" format="default"/>. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
In the case in which there is no transition between replicas (i.e., | In the case in which there is no transition between replicas (i.e., | |||
only a change in access path), there are no special | only a change in access path), there are no special | |||
difficulties in using of this | difficulties in using of this mechanism to effect load balancing. | |||
mechanism to effect load balancing. | </li> | |||
</t> | <li> | |||
<t> | In the case in which the two replicas are sufficiently coordinated | |||
In the case in which the two replicas are sufficiently co-ordinated | as to allow a single client coherent, simultaneous access to both, | |||
as to allow coherent simultaneous access to both by a single client, | there is, in general, no obstacle to the use of migration of particular | |||
there is, in general, no obstacle to use of migration of particular | ||||
clients to effect load balancing. Generally, such simultaneous use | clients to effect load balancing. Generally, such simultaneous use | |||
involves co-operation between servers to ensure that locks granted | involves cooperation between servers to ensure that locks granted | |||
on two co-ordinated replicas cannot conflict and can remain effective | on two coordinated replicas cannot conflict and can remain effective | |||
when transferred to a common replica. | when transferred to a common replica. | |||
</t> | </li> | |||
<t> | <li> | |||
In the case in which a large set of clients are accessing a | In the case in which a large set of clients is accessing a | |||
file system in a read-only fashion, in can be helpful to migrate | file system in a read-only fashion, it can be helpful to migrate | |||
all clients with writable access simultaneously, while using | all clients with writable access simultaneously, while using | |||
load balancing on the set of read-only copies, as long as the | load balancing on the set of read-only copies, as long as the | |||
rules appearing in <xref target="SEC11-EFF-data"/>, designed to | rules in <xref target="SEC11-EFF-data" format="default"/>, | |||
prevent data reversion are adhered to. | which are designed to prevent data reversion, are followed. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
In other cases, the client might not have sufficient guarantees | In other cases, the client might not have sufficient guarantees | |||
of data similarity/coherence to function properly (e.g. the data | of data similarity or coherence to function properly (e.g., the data | |||
in the two replicas is similar but not identical), and the | in the two replicas is similar but not identical), and the | |||
possibility that different clients are updating different replicas | possibility that different clients are updating different replicas | |||
can exacerbate the difficulties, making use of load balancing in | can exacerbate the difficulties, making the use of load balancing in | |||
such situations a perilous enterprise. | such situations a perilous enterprise. | |||
</t> | </t> | |||
<t> | <t> | |||
The protocol | The protocol does not specify how the file system will be moved between | |||
does not specify how the file system will be moved between | servers or how updates to multiple replicas will be coordinated. | |||
servers or how updates to multiple replicas will be co-ordinated. | ||||
It is anticipated that a number of different | It is anticipated that a number of different | |||
server-to-server co-ordination mechanisms might be used with the | server-to-server coordination mechanisms might be used, with the | |||
choice left to the server implementer. The NFSv4.1 protocol | choice left to the server implementer. The NFSv4.1 protocol | |||
specifies the method used to communicate the migration | specifies the method used to communicate the migration | |||
event between client and server. | event between client and server. | |||
</t> | </t> | |||
<t> | <t> | |||
The new location may be, in the case of | In the case of various forms of server clustering, the new location | |||
various forms of server | may be another server providing access to the same physical file system. | |||
clustering, another server providing | The client's | |||
access to the same physical file system. The client's | ||||
responsibilities in dealing with this transition will depend | responsibilities in dealing with this transition will depend | |||
on whether a switch between replicas has occurred and | on whether a switch between replicas has occurred and | |||
the means the server | the means the server has chosen to provide continuity of locking state. | |||
has chosen to provide continuity of locking state. | These issues will be discussed in detail below. | |||
These issues will be discussed in | </t> | |||
detail below. | <t> | |||
</t> | ||||
<t> | ||||
Although a single successor location is typical, multiple | Although a single successor location is typical, multiple | |||
locations may be provided. When multiple locations are | locations may be provided. When multiple locations are | |||
provided, the client will typically use the first one provided. | provided, the client will typically use the first one provided. | |||
If that is | If that is inaccessible for some reason, later ones can be used. In such | |||
inaccessible for some reason, later ones can be used. In such | cases, the client might consider the transition to the new | |||
cases the client might consider the transition to the new | ||||
replica to be a migration event, even though some of the servers | replica to be a migration event, even though some of the servers | |||
involved might not be aware of the use of the server which was | involved might not be aware of the use of the server that was | |||
inaccessible. In such a case, a client might lose access to | inaccessible. In such a case, a client might lose access to | |||
locking state as a result of the access transfer. | locking state as a result of the access transfer. | |||
</t> | </t> | |||
<t> | <t> | |||
When an alternate location is designated as the target for | When an alternate location is designated as the target for | |||
migration, it must designate the same data | migration, it must designate the same data | |||
(with metadata being the same to the degree indicated by the | (with metadata being the same to the degree indicated by the | |||
fs_locations_info attribute). Where file systems are writable, | fs_locations_info attribute). Where file systems are writable, | |||
a change made on the original file system must be visible on | a change made on the original file system must be visible on | |||
all migration targets. Where a file system is not writable | all migration targets. Where a file system is not writable | |||
but represents a read-only copy (possibly periodically | but represents a read-only copy (possibly periodically | |||
updated) of | updated) of | |||
a writable file system, similar requirements apply to the | a writable file system, similar requirements apply to the | |||
propagation of updates. Any change visible in the original | propagation of updates. Any change visible in the original | |||
file system must already be effected on all migration targets, | file system must already be effected on all migration targets, | |||
to avoid any possibility that a client, | to avoid any possibility that a client, in effecting a transition to | |||
in effecting a transition to | the migration target, will see any reversion in file system state. | |||
the migration target, will see any reversion | </t> | |||
in file system state. | </section> | |||
</t> | <section anchor="SEC11-USES-ref" numbered="true" toc="default"> | |||
<name>Referrals</name> | ||||
</section> | <t> | |||
<section title="Referrals" | ||||
anchor="SEC11-USES-ref"> | ||||
<t> | ||||
Referrals allow the server to associate a file system namespace | Referrals allow the server to associate a file system namespace | |||
entry located on | entry located on one server with a file system located on another server. | |||
one server with a file system located on another server. | ||||
When this includes | When this includes | |||
the use of pure referrals, servers are provided a way of | the use of pure referrals, servers are provided a way of | |||
placing a file system in a location | placing a file system in a location within the namespace | |||
within the namespace | ||||
essentially without respect to its physical location on a | essentially without respect to its physical location on a | |||
particular server. | particular server. This allows a single server or a set of servers | |||
This allows a single server or a set of servers | ||||
to present a multi-server namespace that encompasses file systems | to present a multi-server namespace that encompasses file systems | |||
located on a wider range of | located on a wider range of servers. Some likely uses of this facility | |||
servers. Some likely uses of this facility include | include | |||
establishment of site-wide or organization-wide namespaces, | establishment of site-wide or organization-wide namespaces, | |||
with the eventual possibility of combining such | with the eventual possibility of combining such | |||
together into a truly global namespace, such as the one | together into a truly global namespace, such as the one | |||
provided by AFS (the Andrew File System) <xref target="AFS"/>. | provided by AFS (the Andrew File System) <xref target="AFS" format="defau | |||
</t> | lt"/>. | |||
<t> | </t> | |||
<t> | ||||
Referrals occur when a client determines, upon first referencing | Referrals occur when a client determines, upon first referencing | |||
a position in the current namespace, that it is part of a new | a position in the current namespace, that it is part of a new | |||
file system and that the file system is absent. When this | file system and that the file system is absent. When this | |||
occurs, typically upon receiving the error NFS4ERR_MOVED, the | occurs, typically upon receiving the error NFS4ERR_MOVED, the | |||
actual location or locations of the file system can be | actual location or locations of the file system can be | |||
determined by fetching a locations attribute. | determined by fetching a locations attribute. | |||
</t> | </t> | |||
<t> | <t> | |||
The file system location attribute may designate a single | The file system location attribute may designate a single | |||
file system location or multiple file system locations, to | file system location or multiple file system locations, to | |||
be selected based on the needs of the client. The server, | be selected based on the needs of the client. The server, | |||
in the fs_locations_info attribute, may specify priorities to | in the fs_locations_info attribute, may specify priorities to | |||
be associated with various file system location choices. | be associated with various file system location choices. | |||
The server may assign different priorities to different | The server may assign different priorities to different | |||
locations as reported to individual clients, in order to | locations as reported to individual clients, in order to | |||
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> | |||
<t> | <t> | |||
When the fs_locations_info attribute is such that that there are | If the fs_locations_info attribute lists multiple possible targets, | |||
multiple possible targets listed, the relationships among them | the relationships among them may be important to the client in | |||
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"/> | The same rules specified in <xref target="SEC11-USES-migr" format="defau | |||
lt"/> | ||||
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, | |||
as distinguished from the case of replication, there is no | as distinguished from the case of replication, there is no | |||
need to deal with the case of propagation of updates made by | need to deal with the case of propagation of updates made by | |||
the current client, since the current client has not accessed | the current client, since the current client has not accessed | |||
the file system in question. | the file system in question. | |||
</t> | </t> | |||
<t> | <t> | |||
Use of multi-server namespaces is enabled by NFSv4.1 but is not | Use of multi-server namespaces is enabled by NFSv4.1 but is not | |||
required. The use of multi-server namespaces and their scope | required. The use of multi-server namespaces and their scope | |||
will depend on the applications used and system administration | will depend on the applications used and system administration | |||
preferences. | preferences. | |||
</t> | </t> | |||
<t> | <t> | |||
Multi-server namespaces can be established by a single | Multi-server namespaces can be established by a single | |||
server providing a large set of pure referrals to all of the | server providing a large set of pure referrals to all of the | |||
included file systems. Alternatively, a single multi-server | included file systems. Alternatively, a single multi-server | |||
namespace may be administratively segmented with separate | namespace may be administratively segmented with separate | |||
referral file systems (on separate servers) for each | referral file systems (on separate servers) for each | |||
separately administered portion of the namespace. The | separately administered portion of the namespace. The | |||
top-level referral file system or any segment may use | top-level referral file system or any segment may use | |||
replicated referral file systems for higher availability. | replicated referral file systems for higher availability. | |||
</t> | </t> | |||
<t> | <t> | |||
Generally, multi-server namespaces are for the most part | Generally, multi-server namespaces are for the most part | |||
uniform, in that the same data made available to one client | uniform, in that the same data made available to one client | |||
at a given location in the namespace is made available to | at a given location in the namespace is made available to | |||
all clients at that namespace location. However, | all clients at that namespace location. However, | |||
there are facilities | there are facilities | |||
provided that allow different clients to be directed to | provided that allow different clients to be directed to | |||
different sets of data, for reasons such as enabling | different sets of data, for reasons such as enabling | |||
adaptation to such client | adaptation to such client | |||
characteristics as CPU architecture. These facilities are | characteristics as CPU architecture. These facilities are | |||
described in | described in | |||
<xref target="SEC11-fsli-item"/>. | <xref target="SEC11-fsli-item" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that it is possible, when providing a uniform namespace, | Note that it is possible, when providing a uniform namespace, | |||
to provide different location entries to different clients, in | to provide different location entries to different clients in | |||
order to provide each client with a copy of the data physically | order to provide each client with a copy of the data physically | |||
closest to it, or otherwise optimize access (e.g. provide load | closest to it or otherwise optimize access (e.g., provide load | |||
balancing). | balancing). | |||
</t> | </t> | |||
</section> | ||||
</section> | <section anchor="SEC11-USES-changes" numbered="true" toc="default"> | |||
<section title="Changes in a File System Location Attribute" | <name>Changes in a File System Location Attribute</name> | |||
anchor="SEC11-USES-changes"> | <t> | |||
<t> | Although clients will typically fetch a file system location attribute | |||
Although clients will typically fetch a file system | ||||
location attribute | ||||
when first accessing a file system and when NFS4ERR_MOVED | when first accessing a file system and when NFS4ERR_MOVED | |||
is returned, a client can choose to fetch the attribute | is returned, a client can choose to fetch the attribute | |||
periodically, in which case the value fetched may change over | periodically, in which case, the value fetched may change over time. | |||
time. | </t> | |||
</t> | ||||
<t> | ||||
For clients not prepared to access multiple | ||||
replicas simultaneously (see | ||||
<xref target="SEC11-EFF-simul"/>), | ||||
the handling of the various cases of location change are as follows: | ||||
<list style="symbols"> | ||||
<t> | <t> | |||
For clients not prepared to access multiple replicas simultaneously (see | ||||
<xref target="SEC11-EFF-simul" format="default"/>), | ||||
the handling of the various cases of location change are as follows: | ||||
</t> | ||||
<ul spacing="normal"> | ||||
<li> | ||||
Changes in the list of replicas or in the network addresses | Changes in the list of replicas or in the network addresses | |||
associated with replicas do not require immediate action. | associated with replicas do not require immediate action. | |||
The client will typically update its list of replicas to | The client will typically update its list of replicas to | |||
reflect the new information. | reflect the new information. | |||
</t> | </li> | |||
<t> | <li> | |||
Additions to the list of network addresses for the | Additions to the list of network addresses for the | |||
current file system instance need not be acted | current file system instance need not be acted | |||
on promptly. However, to prepare for the case in which | on promptly. However, to prepare for a subsequent | |||
a migration event occurs subsequently, the client can choose | migration event, the client can choose | |||
to take note of the new address and then use it | to take note of the new address and then use it | |||
whenever it needs to switch access to a new | whenever it needs to switch access to a new replica. | |||
replica. | </li> | |||
</t> | <li> | |||
<t> | ||||
Deletions from the list of network addresses for the | Deletions from the list of network addresses for the | |||
current file system instance do not need to be acted on | current file system instance do not require the client to immediately | |||
immediately | cease use of existing access paths, although new connections | |||
by ceasing use of existing access paths although new connections | ||||
are not to be established on addresses that have been deleted. | are not to be established on addresses that have been deleted. | |||
However, clients can choose to act on such deletions | However, clients can choose to act on such deletions | |||
by making preparations for an eventual shift in access which | by preparing for an eventual shift in access, which | |||
would become unavoidable as soon as the | becomes unavoidable as soon as the server returns | |||
server indicates that a particular network access path is | NFS4ERR_MOVED to indicate that a particular network access path is | |||
not usable to access the current file system, | not usable to access the current file system. | |||
by returning NFS4ERR_MOVED. | </li> | |||
</t> | </ul> | |||
</list> | <t> | |||
</t> | For clients that are prepared to access several replicas simultaneously, | |||
<t> | ||||
For clients that are prepared to access several replicas | ||||
simultaneously, | ||||
the following additional cases need to be addressed. As in | the following additional cases need to be addressed. As in | |||
the cases discussed above, changes in the set of replicas | the cases discussed above, changes in the set of replicas | |||
need not be acted upon promptly, although the client has | need not be acted upon promptly, although the client has | |||
the option of adjusting its access even in the absence of | the option of adjusting its access even in the absence of | |||
difficulties that would lead to a new replica to be selected. | difficulties that would lead to the selection of a new replica. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
When a new replica is added which may be accessed | <li> | |||
When a new replica is added, which may be accessed | ||||
simultaneously with one currently in use, the client is free | simultaneously with one currently in use, the client is free | |||
to use the new replica immediately. | to use the new replica immediately. | |||
</t> | </li> | |||
<t> | <li> | |||
When a replica currently in use is deleted from the list, the | When a replica currently in use is deleted from the list, the | |||
client need not cease using it immediately. However, since | client need not cease using it immediately. However, since | |||
the server may subsequently force such use to cease (by | the server may subsequently force such use to cease (by | |||
returning NFS4ERR_MOVED), clients might decide to limit the | returning NFS4ERR_MOVED), clients might decide to limit the | |||
need for later state transfer. For example, new opens might | need for later state transfer. For example, new opens might | |||
be done on other replicas, rather than on one not present in | be done on other replicas, rather than on one not present in | |||
the list. | the list. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="SEC11-TRUNK" numbered="true" toc="default"> | |||
<section title="Trunking without File System Location Information" | <name>Trunking without File System Location Information</name> | |||
anchor="SEC11-TRUNK"> | <t> | |||
<t> | ||||
In situations in which a file system is accessed using two | In situations in which a file system is accessed using two | |||
server-trunkable addresses (as indicated by the same value of the | server-trunkable addresses (as indicated by the same value of the | |||
so_major_id field of the eir_server_owner field returned in | so_major_id field of the eir_server_owner field returned in | |||
response to EXCHANGE_ID), trunked access is allowed even though | response to EXCHANGE_ID), trunked access is allowed even though | |||
there might not be any location entries specifically indicating | there might not be any location entries specifically indicating | |||
the use of trunking for that file system. | the use of trunking for that file system. | |||
</t> | </t> | |||
<t> | <t> | |||
This situation was recognized by <xref target="RFC5661"/>, even though | This situation was recognized by <xref target="RFC5661" format="default"/> | |||
, although | ||||
that document made no explicit mention of trunking and treated the | that document made no explicit mention of trunking and treated the | |||
situation as one of simultaneous use of two distinct file system | situation as one of simultaneous use of two distinct file system | |||
instances, even though, in the explanatory framework now used to | instances. In the explanatory framework now used to | |||
describe the situation, the case is one in which a single file | describe the situation, the case is one in which a single file | |||
system is accessed by two different trunked addresses. | system is accessed by two different trunked addresses. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="SEC11-users" numbered="true" toc="default"> | ||||
<section title="Users and Groups in a Multi-server Namespace" | <name>Users and Groups in a Multi-Server Namespace</name> | |||
anchor="SEC11-users"> | <t> | |||
<t> | ||||
As in the case of a single-server environment (see | As in the case of a single-server environment (see | |||
<xref target="owner_owner_group"/>, | <xref target="owner_owner_group" format="default"/>), | |||
when an owner or group name of the form "id@domain" is assigned to | when an owner or group name of the form "id@domain" is assigned to | |||
a file, there is an implicit promise to return that same string when | a file, there is an implicit promise to return that same string when | |||
the corresponding attribute is interrogated subsequently. In the | the corresponding attribute is interrogated subsequently. In the | |||
case of a multi-server namespace, that same promise applies even if | case of a multi-server namespace, that same promise applies even if | |||
server boundaries have been crossed. Similarly, when the owner | server boundaries have been crossed. Similarly, when the owner | |||
attribute of a file is derived from the security principal which created | attribute of a file is derived from the security principal that created | |||
the file, that attribute should have the same value even if the | the file, that attribute should have the same value even if the | |||
interrogation occurs on a different server from the file creation. | interrogation occurs on a different server from the file creation. | |||
</t> | </t> | |||
<t> | <t> | |||
Similarly, the set of security principals recognized by all the | Similarly, the set of security principals recognized by all the | |||
participating servers needs to be the same, with each such principal | participating servers needs to be the same, with each such principal | |||
having the same credentials, regardless of the particular server | having the same credentials, regardless of the particular server | |||
being accessed. | being accessed. | |||
</t> | </t> | |||
<t> | <t> | |||
In order to meet these requirements, those setting up multi-server | In order to meet these requirements, those setting up multi-server | |||
namespaces will need to limit the servers included so that: | namespaces will need to limit the servers included so that: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
In all cases in which more than a single domain is supported, | In all cases in which more than a single domain is supported, | |||
the requirements stated in RFC8000 <xref target="RFC8000"/> | the requirements stated in RFC 8000 <xref target="RFC8000" format="defaul t"/> | |||
are to be respected. | are to be respected. | |||
</t> | </li> | |||
<t> | <li> | |||
All servers support a common set of domains which includes all of | All servers support a common set of domains that includes all of | |||
the domains clients use and expect to see returned as the domain | the domains clients use and expect to see returned as the domain | |||
portion of an owner or group in the form "id@domain". Note that | portion of an owner or group in the form "id@domain". Note that, | |||
although this set most often consists of a single domain, it is | although this set most often consists of a single domain, it is | |||
possible for multiple domains to be supported. | possible for multiple domains to be supported. | |||
</t> | </li> | |||
<t> | <li> | |||
All servers, for each domain that they support, accept the same set | All servers, for each domain that they support, accept the same set | |||
of user and group ids as valid. | of user and group ids as valid. | |||
</t> | </li> | |||
<t> | <li> | |||
All servers recognize the same set of security principals. For each | All servers recognize the same set of security principals. For each | |||
principal, the same credential is required, independent of the | principal, the same credential is required, independent of the | |||
server being accessed. In addition, the group membership for each such | server being accessed. In addition, the group membership for each such | |||
principal is to be the same, independent of the server accessed. | principal is to be the same, independent of the server accessed. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | Note that there is no requirement in general that the users | |||
Note that there is no requirement in general that the users | corresponding to particular security principals have the same local | |||
corresponding to | representation on each server, even though it is most often the case that | |||
particular security principals have the same local | this is so. | |||
representation on each server, | </t> | |||
even though it is most often the case that this is so. | <t> | |||
</t> | When AUTH_SYS is used, the following additional requirements must be met: | |||
<t> | </t> | |||
When AUTH_SYS is used, the following additional requirements must be | <ul spacing="normal"> | |||
met: | <li> | |||
<list style="symbols"> | Only a single NFSv4 domain can be supported through the use of AUTH_SYS. | |||
<t> | </li> | |||
Only a single NFSv4 domain can be supported through use of AUTH_SYS. | <li> | |||
</t> | ||||
<t> | ||||
The "local" representation of all owners and groups must be the same | The "local" representation of all owners and groups must be the same | |||
on all servers. The word "local" is used here since that is the | on all servers. The word "local" is used here since that is the | |||
way that numeric user and group ids are described in | way that numeric user and group ids are described in | |||
<xref target="owner_owner_group"/>. However, | <xref target="owner_owner_group" format="default"/>. However, | |||
when AUTH_SYS or stringified numeric owners or | when AUTH_SYS or stringified numeric owners or | |||
groups are used, these identifiers are not truly local, since they | groups are used, these identifiers are not truly local, since they | |||
are known to the clients as well as the server. | are known to the clients as well as to the server. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Similarly, when stringified numeric user and group ids are used, the | Similarly, when stringified numeric user and group ids are used, the | |||
"local" representation of all owners and groups must be the same on | "local" representation of all owners and groups must be the same on | |||
all servers, even when AUTH_SYS is not used. | all servers, even when AUTH_SYS is not used. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Additional Client-Side Considerations" | <section anchor="SEC11-csr" numbered="true" toc="default"> | |||
anchor="SEC11-csr"> | <name>Additional Client-Side Considerations</name> | |||
<t> | <t> | |||
When clients make use of servers that implement referrals, | When clients make use of servers that implement referrals, | |||
replication, and | replication, and | |||
migration, care should be taken that a user who mounts a given | migration, care should be taken that a user who mounts a given | |||
file system that includes a referral or a relocated file system | file system that includes a referral or a relocated file system | |||
continues to see a coherent picture of that user-side file system | continues to see a coherent picture of that user-side file system | |||
despite the fact that it contains a number of server-side | despite the fact that it contains a number of server-side | |||
file systems that may be on different servers. | file systems that may be on different servers. | |||
</t> | </t> | |||
<t> | <t> | |||
One important issue is upward navigation from the root of a | One important issue is upward navigation from the root of a | |||
server-side file system to its parent (specified as ".." in UNIX), | server-side file system to its parent (specified as ".." in UNIX), | |||
in the case in which it transitions to that file system as a | in the case in which it transitions to that file system as a | |||
result of referral, migration, or a transition as a result of | result of referral, migration, or a transition as a result of | |||
replication. When the client is at such a point, and it needs to ascend t o | replication. When the client is at such a point, and it needs to ascend t o | |||
the parent, it must go back to the parent as seen within the | the parent, it must go back to the parent as seen within the | |||
multi-server namespace rather than sending a LOOKUPP operation to the | multi-server namespace rather than sending a LOOKUPP operation to the | |||
server, which would result in the parent within that server's | server, which would result in the parent within that server's | |||
single-server namespace. In order to do this, the client | single-server namespace. In order to do this, the client | |||
needs to remember the filehandles that represent such | needs to remember the filehandles that represent such | |||
file system roots and use these instead of sending a | file system roots and use these instead of sending a | |||
LOOKUPP operation to the current server. This will allow the client | LOOKUPP operation to the current server. This will allow the client | |||
to present to applications a consistent namespace, where | to present to applications a consistent namespace, where | |||
upward navigation and downward navigation are consistent. | upward navigation and downward navigation are consistent. | |||
</t> | </t> | |||
<t> | <t> | |||
Another issue concerns refresh of referral locations. When | Another issue concerns refresh of referral locations. When | |||
referrals are used extensively, they may change as server | referrals are used extensively, they may change as server | |||
configurations change. It is expected that clients will cache | configurations change. It is expected that clients will cache | |||
information related to traversing referrals so that future | information related to traversing referrals so that future | |||
client-side requests are resolved locally without server | client-side requests are resolved locally without server | |||
communication. | communication. | |||
This is usually rooted in client-side name look up caching. Clients | This is usually rooted in client-side name look up caching. Clients | |||
should periodically purge this data for referral points in order to | should periodically purge this data for referral points in order to | |||
detect changes in location information. When the change_policy | detect changes in location information. When the change_policy | |||
attribute changes for directories that hold referral entries | attribute changes for directories that hold referral entries | |||
or for the referral entries themselves, clients should consider | or for the referral entries themselves, clients should consider | |||
any associated | any associated | |||
cached referral information to be out of date. | cached referral information to be out of date. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Overview of File Access Transitions" | <section anchor="SEC11-trans-oview" numbered="true" toc="default"> | |||
anchor="SEC11-trans-oview"> | <name>Overview of File Access Transitions</name> | |||
<t> | <t> | |||
File access transitions are of two types: | File access transitions are of two types: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Those that involve a transition from accessing the current | Those that involve a transition from accessing the current | |||
replica to another one in connection with either | replica to another one in connection with either replication or migratio | |||
replication or migration. | n. | |||
How these are dealt with is discussed in | How these are dealt with is discussed in | |||
<xref target="SEC11-EFF"/>. | <xref target="SEC11-EFF" format="default"/>. | |||
</t> | </li> | |||
<t> | <li> | |||
Those in which access to the current file system instance | Those in which access to the current file system instance is retained, w | |||
is retained, while | hile | |||
the network path used to access that instance is changed. | the network path used to access that instance is changed. This case is | |||
This case is | discussed in <xref target="SEC11-nwa" format="default"/>. | |||
discussed in <xref target="SEC11-nwa"/>. | </li> | |||
</t> | </ul> | |||
</list> | </section> | |||
</t> | <section anchor="SEC11-nwa" numbered="true" toc="default"> | |||
<name>Effecting Network Endpoint Transitions</name> | ||||
</section> | <t> | |||
<section title="Effecting Network Endpoint Transitions" | ||||
anchor="SEC11-nwa"> | ||||
<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 | cases, the same fsid, client IDs, filehandles, and stateids are | |||
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 | |||
(i.e. server endpoints which are server-trunkable with one previously | that are available for use | |||
being used) which are available for use. | (i.e., server endpoints that are server-trunkable with one previously | |||
</t> | being used). | |||
<t> | </t> | |||
<list style="symbols"> | <ul spacing="normal"> | |||
<t> | <li> | |||
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 one | also another address | |||
currently in use which 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. | |||
</t> | </li> | |||
<t> | <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. | |||
</t> | </li> | |||
<t> | <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. | when an attempt is made to bind the new connection to it. In this | |||
In this | ||||
case, the client can create a new session to enable continued | case, the client can create a new session to enable continued | |||
access to the existing instance using the new connection, | access to the existing instance using the new connection, | |||
providing for use of existing | providing for the use of existing filehandles, stateids, and | |||
filehandles, stateids, and client ids while providing continuity | client ids while supplying continuity of locking state. | |||
of locking state. | </li> | |||
</t> | <li> | |||
<t> | When there is no potential replacement address in use, and there | |||
When there is no potential replacement address in use and there | are no valid addresses session-trunkable with the one whose use is | |||
are no | ||||
valid addresses session-trunkable with the one whose use is | ||||
to be discontinued, other server-trunkable addresses may be | to be discontinued, other server-trunkable addresses may be | |||
used to provide continued access. Although use of CREATE_SESSION | used to provide continued access. Although the use of CREATE_SESSION | |||
is available to provide continued access to the existing instance, | is available to provide continued access to the existing instance, | |||
servers have the option of providing continued access to the | servers have the option of providing continued access to the | |||
existing session through the new network access | existing session through the new network access path in a fashion | |||
path in a fashion similar to | similar to that provided by session migration (see | |||
that provided by session migration (see | <xref target="SEC11-trans-locking" format="default"/>). | |||
<xref target="SEC11-trans-locking"/>). | ||||
To take advantage of this | To take advantage of this | |||
possibility, clients can perform an initial BIND_CONN_TO_SESSION, | possibility, clients can perform an initial BIND_CONN_TO_SESSION, | |||
as in the previous case, and use CREATE_SESSION only if that | as in the previous case, and use CREATE_SESSION only if that fails. | |||
fails. | </li> | |||
</t> | </ul> | |||
</list> | </section> | |||
</t> | <section anchor="SEC11-EFF" numbered="true" toc="default"> | |||
<name>Effecting File System Transitions</name> | ||||
</section> | <t> | |||
<section title="Effecting File System Transitions" | ||||
anchor="SEC11-EFF"> | ||||
<t> | ||||
There are a range of situations in which there is a change to be | There are a range of situations in which there is a change to be | |||
effected in the set of replicas used to access a particular | effected in the set of replicas used to access a particular | |||
file system. Some of these may involve an expansion or | file system. Some of these may involve an expansion or | |||
contraction of the set of replicas used as discussed in | contraction of the set of replicas used as discussed in | |||
<xref target="SEC11-EFF-simul"/> below. | <xref target="SEC11-EFF-simul" format="default"/> below. | |||
</t> | </t> | |||
<t> | <t> | |||
For reasons explained in that section, most transitions will involve | For reasons explained in that section, most transitions will involve | |||
a transition from a single replica to a corresponding replacement | a transition from a single replica to a corresponding replacement | |||
replica. When effecting replica transition, some types of | replica. When effecting replica transition, some types of | |||
sharing between the replicas may affect handling of the | sharing between the replicas may affect handling of the | |||
transition as described in | transition as described in | |||
Sections <xref target="SEC11-EFF-fh" format="counter"/> | Sections <xref target="SEC11-EFF-fh" format="counter"/> | |||
through <xref target="SEC11-EFF-data" format="counter"/> below. | through <xref target="SEC11-EFF-data" format="counter"/> below. | |||
The attribute fs_locations_info provides helpful information | The attribute fs_locations_info provides helpful information | |||
to allow the client to determine the degree of inter-replica | to allow the client to determine the degree of inter-replica | |||
sharing. | sharing. | |||
</t> | </t> | |||
<t> | <t> | |||
With regard to some types of state, the degree of continuity | With regard to some types of state, the degree of continuity | |||
across the transition | across the transition depends on the occasion prompting the | |||
depends on the occasion prompting the transition, with | transition, with transitions initiated by the servers | |||
transitions initiated by the servers | (i.e., migration) offering much more scope for a nondisruptive | |||
(i.e. migration) offering much more scope for a non-disruptive | ||||
transition than cases in which the client on its own | transition than cases in which the client on its own | |||
shifts its access to | shifts its access to another replica (i.e., replication). | |||
another replica (i.e. replication). This issue | This issue potentially applies to locking state and to session | |||
potentially applies to | state, which are dealt with below as follows: | |||
locking state and to session state, which are dealt with below as | </t> | |||
follows: | <ul spacing="normal"> | |||
<list style="symbols"> | <li> | |||
<t> | ||||
An introduction to the possible means of providing continuity in | An introduction to the possible means of providing continuity in | |||
these areas appears in <xref target="SEC11-EFF-lock"/> below. | these areas appears in <xref target="SEC11-EFF-lock" format="default"/> | |||
</t> | below. | |||
<t> | </li> | |||
<li> | ||||
Transparent State Migration is introduced in | Transparent State Migration is introduced in | |||
<xref target="SEC11-trans-locking"/>. | <xref target="SEC11-trans-locking" format="default"/>. | |||
The possible transfer of | The possible transfer of | |||
session state is addressed there as well. | session state is addressed there as well. | |||
</t> | </li> | |||
<t> | <li> | |||
The client handling of transitions, including determining how to | The client handling of transitions, including determining how to | |||
deal with the various means that the server might take to | deal with the various means that the server might take to | |||
supply effective continuity of locking state is discussed in | supply effective continuity of locking state, is discussed in | |||
<xref target="SEC11-trans-client"/>. | <xref target="SEC11-trans-client" format="default"/>. | |||
</t> | </li> | |||
<t> | <li> | |||
The servers' (source and destination) responsibilities | The source and destination servers' responsibilities | |||
in effecting Transparent Migration | in effecting Transparent State Migration | |||
of locking and session state are discussed in | of locking and session state are discussed in | |||
<xref target="SEC11-trans-server"/>. | <xref target="SEC11-trans-server" format="default"/>. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <section anchor="SEC11-EFF-simul" numbered="true" toc="default"> | |||
<section title="File System Transitions and Simultaneous Access" | <name>File System Transitions and Simultaneous Access</name> | |||
anchor="SEC11-EFF-simul"> | <t> | |||
<t> | ||||
The fs_locations_info attribute (described in | The fs_locations_info attribute (described in | |||
<xref target="SEC11-li-new"/>) | <xref target="SEC11-li-new" format="default"/>) | |||
may indicate that two replicas | may indicate that two replicas | |||
may be used simultaneously, although some situations in which such | may be used simultaneously, although some situations in which such | |||
simultaneous access is permitted are more appropriately described | simultaneous access is permitted are more appropriately described | |||
as instances of trunking (see <xref target="SEC11-USES-repl-trunk"/>). | as instances of trunking (see <xref target="SEC11-USES-repl-trunk" format ="default"/>). | |||
Although situations | Although situations | |||
in which multiple replicas may be accessed simultaneously are | in which multiple replicas may be accessed simultaneously are | |||
somewhat similar to those in which a single replica is | somewhat similar to those in which a single replica is | |||
accessed by multiple network addresses, there are important | accessed by multiple network addresses, there are important | |||
differences, since locking state is not shared among multiple | differences since locking state is not shared among multiple | |||
replicas. | replicas. | |||
</t> | </t> | |||
<t> | <t> | |||
Because of this difference in state handling, many clients will | Because of this difference in state handling, many clients will | |||
not have the ability to take advantage of the fact that such | not have the ability to take advantage of the fact that such | |||
replicas represent the same data. Such clients will not be | replicas represent the same data. Such clients will not be | |||
prepared to use multiple replicas simultaneously but will access | prepared to use multiple replicas simultaneously but will access | |||
each file system using only a single replica, although the | each file system using only a single replica, although the | |||
replica selected might make multiple server-trunkable addresses | replica selected might make multiple server-trunkable addresses | |||
available. | available. | |||
</t> | </t> | |||
<t> | <t> | |||
Clients who are prepared to use multiple replicas simultaneously | Clients who are prepared to use multiple replicas simultaneously | |||
will divide opens among replicas however they choose. Once that | can divide opens among replicas however they choose. Once that | |||
choice is made, | choice is made, any subsequent transitions will treat the set of locking | |||
any subsequent transitions will treat the set of locking | ||||
state associated with each replica as a single entity. | state associated with each replica as a single entity. | |||
</t> | </t> | |||
<t> | <t> | |||
For example, if one of the replicas become unavailable, | For example, if one of the replicas become unavailable, access will be | |||
access will be | transferred to a different replica, which is also capable of | |||
transferred to a different replica, also capable of | ||||
simultaneous access with the one still in use. | simultaneous access with the one still in use. | |||
</t> | </t> | |||
<t> | <t> | |||
When there is no such replica, the transition may be to the | When there is no such replica, the transition may be to the | |||
replica already in use. At this point, the client has a | replica already in use. At this point, the client has a | |||
choice between merging the locking state for the two replicas | choice between merging the locking state for the two replicas | |||
under the aegis of the sole replica in use or treating these | under the aegis of the sole replica in use or treating these | |||
separately, until another replica capable of simultaneous | separately until another replica capable of simultaneous | |||
access presents itself. | access presents itself. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Filehandles and File System Transitions" | <section anchor="SEC11-EFF-fh" numbered="true" toc="default"> | |||
anchor="SEC11-EFF-fh"> | <name>Filehandles and File System Transitions</name> | |||
<t> | ||||
<t> | ||||
There are a number of ways in which filehandles can be handled | There are a number of ways in which filehandles can be handled | |||
across a file system transition. These can be divided into | across a file system transition. These can be divided into | |||
two broad classes depending upon whether the two file systems | two broad classes depending upon whether the two file systems | |||
across which the transition happens share sufficient state to | across which the transition happens share sufficient state to | |||
effect some sort of continuity of file system handling. | effect some sort of continuity of file system handling. | |||
</t> | </t> | |||
<t> | <t> | |||
When there is no such cooperation in filehandle assignment, | When there is no such cooperation in filehandle assignment, | |||
the two file systems are reported as being in different | the two file systems are reported as being in different | |||
handle classes. In this case, | handle classes. In this case, | |||
all filehandles are assumed to expire as part of the | all filehandles are assumed to expire as part of the | |||
file system transition. Note that this behavior does not | file system transition. Note that this behavior does not | |||
depend on the fh_expire_type attribute and supersedes | depend on the fh_expire_type attribute and supersedes | |||
the specification | the specification | |||
of the FH4_VOL_MIGRATION bit, which only affects behavior when | of the FH4_VOL_MIGRATION bit, which only affects behavior when | |||
fs_locations_info is not available. | fs_locations_info is not available. | |||
</t> | </t> | |||
<t> | <t> | |||
When there is cooperation in filehandle assignment, | When there is cooperation in filehandle assignment, | |||
the two file systems are reported as being in the same | the two file systems are reported as being in the same | |||
handle classes. In this case, | handle classes. In this case, | |||
persistent filehandles remain valid after the file system | persistent filehandles remain valid after the file system | |||
transition, while volatile filehandles (excluding those | transition, while volatile filehandles (excluding those | |||
that are only volatile due to the FH4_VOL_MIGRATION bit) are | that are only volatile due to the FH4_VOL_MIGRATION bit) are | |||
subject to expiration on the target server. | subject to expiration on the target server. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Fileids and File System Transitions" | <section anchor="SEC11-EFF-fileid" numbered="true" toc="default"> | |||
anchor="SEC11-EFF-fileid"> | <name>Fileids and File System Transitions</name> | |||
<t> | <t> | |||
In NFSv4.0, the issue of continuity of fileids in the event | In NFSv4.0, the issue of continuity of fileids in the event | |||
of a file system transition was not addressed. The general | of a file system transition was not addressed. The general | |||
expectation had been that in situations in | expectation had been that in situations in | |||
which the two file system instances are created by a single vendor | which the two file system instances are created by a single vendor | |||
using some sort of file system image copy, fileids would be | using some sort of file system image copy, fileids would be | |||
consistent across the transition, while in the analogous | consistent across the transition, while in the analogous | |||
multi-vendor transitions they would not. This poses difficulties, | multi-vendor transitions they would not. This poses difficulties, | |||
especially for the client without special knowledge | especially for the client without special knowledge | |||
of the transition mechanisms adopted by the server. Note | of the transition mechanisms adopted by the server. Note | |||
that although fileid is not a REQUIRED attribute, many servers | that although fileid is not a <bcp14>REQUIRED</bcp14> attribute, many se rvers | |||
support fileids and many clients provide APIs that depend on fileids. | support fileids and many clients provide APIs that depend on fileids. | |||
</t> | </t> | |||
<t> | <t> | |||
It is important to note that while clients themselves may have no | It is important to note that while clients themselves may have no | |||
trouble with a fileid changing as a result of a file system | trouble with a fileid changing as a result of a file system | |||
transition event, applications do typically have access to the | transition event, applications do typically have access to the | |||
fileid (e.g., via stat). The result is that an | fileid (e.g., via stat). The result is that an | |||
application may work perfectly well if there is no file system | application may work perfectly well if there is no file system | |||
instance transition or if any such transition is among instances | instance transition or if any such transition is among instances | |||
created by a single vendor, yet be unable to deal with the | created by a single vendor, yet be unable to deal with the | |||
situation in which a multi-vendor transition occurs at the wrong | situation in which a multi-vendor transition occurs at the wrong | |||
time. | time. | |||
</t> | </t> | |||
<t> | <t> | |||
Providing the same fileids in a multi-vendor (multiple server | Providing the same fileids in a multi-vendor (multiple server | |||
vendors) environment has generally been held to be quite difficult. | vendors) environment has generally been held to be quite difficult. | |||
While there is work to be done, it needs to be pointed out that | While there is work to be done, it needs to be pointed out that | |||
this difficulty is partly self-imposed. Servers have typically | this difficulty is partly self-imposed. Servers have typically | |||
identified fileid with inode number, i.e. with a quantity used to | identified fileid with inode number, i.e. with a quantity used to | |||
find the file in question. This identification poses special | find the file in question. This identification poses special | |||
difficulties for migration of a file system between vendors | difficulties for migration of a file system between vendors | |||
where assigning | where assigning | |||
the same index to a given file may not be possible. Note here that | the same index to a given file may not be possible. Note here that | |||
a fileid is not required to be useful to find the file in | a fileid is not required to be useful to find the file in | |||
question, only that it is unique within the given file system. Servers | question, only that it is unique within the given file system. Servers | |||
prepared to accept a fileid as a single piece of metadata and store | prepared to accept a fileid as a single piece of metadata and store | |||
it apart from the value used to index the file information can | it apart from the value used to index the file information can | |||
relatively easily maintain a fileid value across a migration event, | relatively easily maintain a fileid value across a migration event, | |||
allowing a truly transparent migration event. | allowing a truly transparent migration event. | |||
</t> | </t> | |||
<t> | <t> | |||
In any case, where servers can provide continuity of fileids, they | In any case, where servers can provide continuity of fileids, they | |||
should, and the client should be able to find out that such | should, and the client should be able to find out that such | |||
continuity is available and take appropriate action. Information | continuity is available and take appropriate action. Information | |||
about the continuity (or lack thereof) of fileids across a file | about the continuity (or lack thereof) of fileids across a file | |||
system transition is represented by specifying whether the file systems | system transition is represented by specifying whether the file systems | |||
in question are of the same fileid class. | in question are of the same fileid class. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that when consistent fileids do not exist across a | Note that when consistent fileids do not exist across a | |||
transition (either because there is no continuity of fileids | transition (either because there is no continuity of fileids | |||
or because fileid is not a supported attribute on one of | or because fileid is not a supported attribute on one of | |||
instances involved), and there are | instances involved), and there are | |||
no reliable filehandles across a transition event (either because | no reliable filehandles across a transition event (either because | |||
there is no filehandle continuity or because the filehandles are | there is no filehandle continuity or because the filehandles are | |||
volatile), the client is in a position where it cannot verify | volatile), the client is in a position where it cannot verify | |||
that files it was accessing before the transition are the | that files it was accessing before the transition are the | |||
same objects. It is forced to assume that no object has been | same objects. It is forced to assume that no object has been | |||
renamed, and, unless there are guarantees that provide this | renamed, and, unless there are guarantees that provide this | |||
(e.g., the file system is read-only), problems for applications | (e.g., the file system is read-only), problems for applications | |||
may occur. Therefore, use of such configurations should be | may occur. Therefore, use of such configurations should be | |||
limited to situations where the problems that this may cause | limited to situations where the problems that this may cause | |||
can be tolerated. | can be tolerated. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Fsids and File System Transitions" | <section anchor="SEC11-EFF-fsid" numbered="true" toc="default"> | |||
anchor="SEC11-EFF-fsid"> | <name>Fsids and File System Transitions</name> | |||
<t> | <t> | |||
Since fsids are generally only unique on a per-server basis, | Since fsids are generally only unique on a per-server basis, | |||
it is likely that they will change during a file system | it is likely that they will change during a file system | |||
transition. | transition. | |||
Clients should not make the fsids received | Clients should not make the fsids received | |||
from the server visible to applications since they may not be | from the server visible to applications since they may not be | |||
globally unique, and because they may change during a file | globally unique, and because they may change during a file | |||
system transition event. Applications are best served if they | system transition event. Applications are best served if they | |||
are isolated from such transitions to the extent possible. | are isolated from such transitions to the extent possible. | |||
</t> | </t> | |||
<t> | <t> | |||
Although normally a single source file system will transition | Although normally a single source file system will transition | |||
to a single target file system, there is a provision for splitting | to a single target file system, there is a provision for splitting | |||
a single source file system into multiple target file systems, by | a single source file system into multiple target file systems, by | |||
specifying the FSLI4F_MULTI_FS flag. | specifying the FSLI4F_MULTI_FS flag. | |||
</t> | </t> | |||
<section anchor="SEC11-EFF-fsid-split" | <section anchor="SEC11-EFF-fsid-split" numbered="true" toc="default"> | |||
title="File System Splitting"> | <name>File System Splitting</name> | |||
<t> | <t> | |||
When a file system transition is made and the fs_locations_info | When a file system transition is made and the fs_locations_info | |||
indicates that the file system in question might be split into | indicates that the file system in question might be split into | |||
multiple file systems (via the FSLI4F_MULTI_FS flag), the client | multiple file systems (via the FSLI4F_MULTI_FS flag), the client | |||
SHOULD do GETATTRs to determine the fsid attribute on all known | <bcp14>SHOULD</bcp14> do GETATTRs to determine the fsid attribute on a ll known | |||
objects within the file system undergoing transition to determine | objects within the file system undergoing transition to determine | |||
the new file system boundaries. | the new file system boundaries. | |||
</t> | </t> | |||
<t> | <t> | |||
Clients might choose to | Clients might choose to | |||
maintain the fsids passed to existing applications | maintain the fsids passed to existing applications | |||
by mapping all of the fsids for the descendant file systems to | by mapping all of the fsids for the descendant file systems to | |||
the common fsid used for the original file system. | the common fsid used for the original file system. | |||
</t> | </t> | |||
<t> | <t> | |||
Splitting a file system can be done on a transition between | Splitting a file system can be done on a transition between | |||
file systems of the same fileid | file systems of the same fileid | |||
class, since the fact that fileids are unique within the | class, since the fact that fileids are unique within the | |||
source file system ensure they will be unique in each of the | source file system ensure they will be unique in each of the | |||
target file systems. | target file systems. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="SEC11-EFF-change" | <section anchor="SEC11-EFF-change" numbered="true" toc="default"> | |||
title="The Change Attribute and File System Transitions"> | <name>The Change Attribute and File System Transitions</name> | |||
<t> | <t> | |||
Since the change attribute is defined as a server-specific one, | Since the change attribute is defined as a server-specific one, | |||
change attributes fetched from one server are normally presumed to | change attributes fetched from one server are normally presumed to | |||
be invalid on another server. Such a presumption is troublesome | be invalid on another server. Such a presumption is troublesome | |||
since it would invalidate all cached change attributes, requiring | since it would invalidate all cached change attributes, requiring | |||
refetching. Even more disruptive, the absence of any assured | refetching. Even more disruptive, the absence of any assured | |||
continuity for the change attribute means that even if the same | continuity for the change attribute means that even if the same | |||
value is retrieved on refetch, no conclusions can be drawn as to whether | value is retrieved on refetch, no conclusions can be drawn as to whether | |||
the object in question has changed. The identical change | the object in question has changed. The identical change | |||
attribute could be merely an artifact of a modified file with | attribute could be merely an artifact of a modified file with | |||
a different change attribute construction algorithm, with that | a different change attribute construction algorithm, with that | |||
new algorithm just happening to result in an identical change | new algorithm just happening to result in an identical change | |||
value. | value. | |||
</t> | </t> | |||
<t> | <t> | |||
When the two file systems have consistent change attribute formats, | When the two file systems have consistent change attribute formats, | |||
and this fact is communicated to the client by reporting | and this fact is communicated to the client by reporting | |||
in the same change class, the | in the same change class, the | |||
client may assume a continuity of change attribute construction | client may assume a continuity of change attribute construction | |||
and handle this situation just as it would be handled without | and handle this situation just as it would be handled without | |||
any file system transition. | any file system transition. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="SEC11-EFF-wv" | <section anchor="SEC11-EFF-wv" numbered="true" toc="default"> | |||
title="Write Verifiers and File System Transitions"> | <name>Write Verifiers and File System Transitions</name> | |||
<t> | <t> | |||
In a file system transition, the two file systems might be | In a file system transition, the two file systems might be | |||
cooperating in the handling of unstably written data. | cooperating in the handling of unstably written data. | |||
Clients can determine if this is the | Clients can determine if this is the | |||
case, by seeing if the two file systems belong to the same | case by seeing if the two file systems belong to the same | |||
write-verifier class. When this is the case, write | write-verifier class. When this is the case, write | |||
verifiers returned | verifiers returned | |||
from one system may be compared to those returned by the | from one system may be compared to those returned by the | |||
other and superfluous | other and superfluous writes can be avoided. | |||
writes avoided. | </t> | |||
</t> | <t> | |||
<t> | ||||
When two file systems belong to different | When two file systems belong to different | |||
write-verifier classes, any verifier | write-verifier classes, any verifier | |||
generated by one must not be compared to one provided by the | generated by one must not be compared to one provided by the | |||
other. Instead, the two verifiers should be treated as not | other. Instead, the two verifiers should be treated as not | |||
equal even when | equal even when the values are identical. | |||
the values are identical. | </t> | |||
</t> | </section> | |||
</section> | <section anchor="SEC11-EFF-rdc" numbered="true" toc="default"> | |||
<section anchor="SEC11-EFF-rdc" | <name>READDIR Cookies and Verifiers and File System Transitions</name> | |||
title="Readdir Cookies and Verifiers and File System Transitions"> | <t> | |||
<t> | ||||
In a file system transition, the two file systems might be | In a file system transition, the two file systems might be | |||
consistent in their handling of READDIR cookies and verifiers. | consistent in their handling of READDIR cookies and verifiers. | |||
Clients can determine if this is the | Clients can determine if this is the | |||
case, by seeing if the two file systems belong to the same | case by seeing if the two file systems belong to the same | |||
readdir class. When this is the | readdir class. When this is the case, readdir class, READDIR | |||
case, readdir class, READDIR | cookies, and verifiers | |||
cookies and verifiers | from one system will be recognized by the other, and | |||
from one system will be recognized by the other and | READDIR operations started on one server can be validly | |||
READDIR operations started on one server can be validly | continued on the other simply by presenting the | |||
continued on the other, simply by presenting the | ||||
cookie and verifier returned by a READDIR operation done | cookie and verifier returned by a READDIR operation done | |||
on the first file system to the second. | on the first file system to the second. | |||
</t> | </t> | |||
<t> | <t> | |||
When two file systems belong to different | When two file systems belong to different | |||
readdir classes, any READDIR | readdir classes, any READDIR cookie and verifier | |||
cookie and verifier | generated by one is not valid on the second and must not | |||
generated by one is not valid on the second, and must not | ||||
be presented to that server by the client. The client | be presented to that server by the client. The client | |||
should act as if the verifier were rejected. | should act as if the verifier were rejected. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="SEC11-EFF-data" | <section anchor="SEC11-EFF-data" numbered="true" toc="default"> | |||
title="File System Data and File System Transitions"> | <name>File System Data and File System Transitions</name> | |||
<t> | <t> | |||
When multiple replicas exist and are used simultaneously or in | When multiple replicas exist and are used simultaneously or in | |||
succession by a client, applications using them will | succession by a client, applications using them will normally expect | |||
normally expect | that they contain either the same data or data that is consistent with | |||
that they contain either the same data or data that is | ||||
consistent with | ||||
the normal sorts of changes that are made by other clients | the normal sorts of changes that are made by other clients | |||
updating the data of the file system | updating the data of the file system | |||
(with metadata being the same to the degree indicated by the | (with metadata being the same to the degree indicated by the | |||
fs_locations_info attribute). However, when | fs_locations_info attribute). However, when multiple file systems are | |||
multiple file systems are | ||||
presented as replicas of one another, the precise relationship | presented as replicas of one another, the precise relationship | |||
between the data of one and the data of another is not, as a | between the data of one and the data of another is not, as a | |||
general matter, specified by the NFSv4.1 protocol. It is quite | general matter, specified by the NFSv4.1 protocol. It is quite | |||
possible to present as replicas file systems where the data of | possible to present as replicas file systems where the data of | |||
those file systems is sufficiently different that some applications | those file systems is sufficiently different that some applications | |||
have problems dealing with the transition between replicas. The | have problems dealing with the transition between replicas. The | |||
namespace will typically be constructed so that applications can | namespace will typically be constructed so that applications can | |||
choose an appropriate level of support, so that in one position in | choose an appropriate level of support, so that in one position in | |||
the namespace a varied set of replicas might be listed, while in | the namespace, a varied set of replicas might be listed, while in | |||
another only those that are up-to-date would be considered replicas. | another, only those that are up-to-date would be considered replicas. | |||
The protocol does define three special cases | The protocol does define three special cases of the relationship among | |||
of the relationship among | ||||
replicas to be specified by the server and relied upon by clients: | replicas to be specified by the server and relied upon by clients: | |||
</t> | ||||
<list style='symbols'> | <ul spacing="normal"> | |||
<t> | <li> | |||
When multiple replicas exist and are used simultaneously | When multiple replicas exist and are used simultaneously | |||
by a client (see the FSLIB4_CLSIMUL definition within | by a client (see the FSLIB4_CLSIMUL definition within | |||
fs_locations_info), they must designate the same | fs_locations_info), they must designate the same | |||
data. Where file systems are writable, a change made on | data. Where file systems are writable, a change made on | |||
one instance must be visible on all instances at the same | one instance must be visible on all instances at the same | |||
time, regardless of whether the interrogated instance is the | time, regardless of whether the interrogated instance is the | |||
one on which the modification was done. | one on which the modification was done. | |||
This allows a client to use these replicas | This allows a client to use these replicas | |||
simultaneously without any special adaptation to the fact | simultaneously without any special adaptation to the fact | |||
that there are multiple replicas, beyond adapting to the fact | that there are multiple replicas, beyond adapting to the fact | |||
that locks obtained on one replica are maintained separately | that locks obtained on one replica are maintained separately | |||
(i.e. under a different client ID). | (i.e., under a different client ID). | |||
In this case, locks (whether share reservations or | In this case, locks (whether share reservations or | |||
byte-range locks) and delegations obtained on one | byte-range locks) and delegations obtained on one | |||
replica are immediately reflected on all replicas, in the | replica are immediately reflected on all replicas, in the | |||
sense that access from all other servers is prevented | sense that access from all other servers is prevented | |||
regardless of | regardless of the replica used. However, because the servers are | |||
the replica used. However, because the servers are | not required to treat two associated client IDs as | |||
not required | ||||
to treat two associated client IDs as | ||||
representing the same client, it is best to | representing the same client, it is best to | |||
access each file using | access each file using only a single client ID. | |||
only a single client ID. | </li> | |||
</t> | <li> | |||
<t> | When one replica is designated as the successor instance to another | |||
When one replica is designated as the | existing instance after the return of NFS4ERR_MOVED (i.e., the case of | |||
successor instance to another | ||||
existing instance after return NFS4ERR_MOVED | ||||
(i.e., the case of | ||||
migration), the client may depend on the fact that all changes | migration), the client may depend on the fact that all changes | |||
written to stable storage on the original instance | written to stable storage on the original instance | |||
are written to stable storage of the successor (uncommitted | are written to stable storage of the successor (uncommitted | |||
writes are dealt with in | writes are dealt with in <xref target="SEC11-EFF-wv" format="default"/ | |||
<xref target="SEC11-EFF-wv" /> above). | > above). | |||
</t> | </li> | |||
<t> | <li> | |||
Where a file system is not writable but represents a read-only | Where a file system is not writable but represents a read-only | |||
copy (possibly periodically updated) of a writable file system, | copy (possibly periodically updated) of a writable file system, | |||
clients have similar requirements with regard | clients have similar requirements with regard to the propagation | |||
to the propagation | of updates. They may need a guarantee that any change visible on | |||
of updates. They may need a guarantee that | the original file system instance must be immediately visible on | |||
any change visible on | any replica before the client transitions access to that replica, | |||
the original file system instance must | in order to avoid any possibility that a client, in effecting a transi | |||
be immediately visible on | tion to a | |||
any replica before the client | ||||
transitions access to that replica, | ||||
in order to | ||||
avoid any possibility that a client, | ||||
in effecting a transition to a | ||||
replica, will see any reversion in file system state. | replica, will see any reversion in file system state. | |||
The specific | The specific means of this guarantee varies based on the value of | |||
means of this guarantee varies based on the value of | the fss_type field that is reported as part of the fs_status attribute | |||
the fss_type field that is | (see <xref target="fs_status" format="default"/>). | |||
reported as part of the fs_status attribute | Since these file systems are presumed to be unsuitable for simultaneou | |||
(see <xref target="fs_status" />). | s use, | |||
Since these file systems are presumed | there is no specification of how locking is handled; in general, locks | |||
to be unsuitable for simultaneous use, | obtained on one file | |||
there is no specification of how | ||||
locking is handled; in general, locks obtained on one file | ||||
system will be separate from those on others. | system will be separate from those on others. | |||
Since these are expected to be read-only file systems, | Since these are expected to be read-only file systems, | |||
this is not | this is not likely to pose an issue for clients or applications. | |||
likely to pose an issue for clients or applications. | </li> | |||
</t> | </ul> | |||
</list> | <t> | |||
</t> | When none of these special situations applies, there is no basis | |||
<t> | ||||
When none of these special situations apply, there is no basis, | ||||
within the protocol for the client to make assumptions about the | within the protocol for the client to make assumptions about the | |||
contents of a replica file system or its relationship to previous | contents of a replica file system or its relationship to previous | |||
file system instances. Thus switching between nominally | file system instances. Thus, switching between nominally | |||
identical read-write file | identical read-write file systems would not be possible because either the | |||
systems would not be possible, because either the | client does not use the fs_locations_info attribute, or the server does no | |||
client does not use or the server does not support the fs_locations_info | t support it. | |||
attribute. | </t> | |||
</t> | </section> | |||
</section> | <section anchor="SEC11-EFF-lock" numbered="true" toc="default"> | |||
<section title="Lock State and File System Transitions" | <name>Lock State and File System Transitions</name> | |||
anchor="SEC11-EFF-lock"> | <t> | |||
<t> | ||||
While accessing a file system, clients obtain locks enforced | While accessing a file system, clients obtain locks enforced | |||
by the server which may prevent actions by other clients | by the server, which may prevent actions by other clients | |||
that are inconsistent with those locks. | that are inconsistent with those locks. | |||
</t> | </t> | |||
<t> | <t> | |||
When access is transferred between replicas, clients need to | When access is transferred between replicas, clients need to | |||
be assured that the actions disallowed by holding these locks | be assured that the actions disallowed by holding these locks | |||
cannot have occurred during the transition. This can be ensured | cannot have occurred during the transition. This can be ensured | |||
by the methods below. Unless at least one of these is implemented, | by the methods below. Unless at least one of these is implemented, | |||
clients will not be assured of continuity of lock | clients will not be assured of continuity of lock | |||
possession across a migration event. | possession across a migration event: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
Providing the client an opportunity to re-obtain his | <li> | |||
locks via a per-fs grace | <t> | |||
Providing the client an opportunity to re-obtain his locks via a per-fs | ||||
grace | ||||
period on the destination server, denying all clients using the | period on the destination server, denying all clients using the | |||
destination file system the | destination file system the | |||
opportunity to obtain new locks that conflict which those held | opportunity to obtain new locks that conflict with those held | |||
by the transferred client as long as that client | by the transferred client as long as that client | |||
has not completed its per-fs grace period. Because the lock reclaim | has not completed its per-fs grace period. Because the lock reclaim | |||
mechanism was originally defined to support server reboot, it | mechanism was originally defined to support server reboot, it | |||
implicitly assumes that file handles will, upon reclaim, will | implicitly assumes that filehandles will, upon reclaim, | |||
be the same as those at open. In the case of migration, this | be the same as those at open. In the case of migration, this | |||
requires that source and destination servers use the same | requires that source and destination servers use the same | |||
filehandles, as evidenced by using the same server scope | filehandles, as evidenced by using the same server scope | |||
(see <xref target="Server_Scope"/>) | (see <xref target="Server_Scope" format="default"/>) | |||
or by showing this | or by showing this agreement using fs_locations_info | |||
agreement using fs_locations_info | (see <xref target="SEC11-EFF-fh" format="default"/> above). | |||
(see <xref target="SEC11-EFF-fh"/> above). | </t> | |||
<vspace blankLines="1"/> | <t> | |||
Note that such a grace period can be implemented without | Note that such a grace period can be implemented without | |||
interfering with the ability of non-transferred clients to | interfering with the ability of non-transferred clients to | |||
obtain new locks while it is going on. As long as the destination | obtain new locks while it is going on. As long as the destination | |||
server is aware of the transferred locks, it can distinguish requests | server is aware of the transferred locks, it can distinguish requests | |||
to obtain new locks that contrast with existing locks | to obtain new locks that contrast with existing locks | |||
from those that do not, allowing it to treat such client requests | from those that do not, allowing it to treat such client requests | |||
without reference to the ongoing grace period. | without reference to the ongoing grace period. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
Locking state can be transferred as part of the transition | Locking state can be transferred as part of the transition | |||
by providing Transparent State Migration as | by providing Transparent State Migration as | |||
described in <xref target="SEC11-trans-locking"/>. | described in <xref target="SEC11-trans-locking" format="default"/>. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Of these, Transparent State Migration provides the smoother | Of these, Transparent State Migration provides the smoother | |||
experience for clients in that there is no need to go through a | experience for clients in that there is no need to go through a | |||
reclaim process | reclaim process before new locks can be obtained; however, it requires | |||
before new locks can be obtained. However, it requires | a greater degree of inter-server coordination. In general, the | |||
a greater degree of inter-server co-ordination. In general, the | ||||
servers taking part in migration are free to provide either | servers taking part in migration are free to provide either | |||
facility. However, when the filehandles can differ across the | facility. However, when the filehandles can differ across the | |||
migration event, Transparent State Migration is the only | migration event, Transparent State Migration is the only | |||
available means of providing the needed functionality. | available means of providing the needed functionality. | |||
</t> | </t> | |||
<t> | <t> | |||
It should be noted that these two methods are not mutually | It should be noted that these two methods are not mutually | |||
exclusive and that a server might well provide both. In | exclusive and that a server might well provide both. In | |||
particular, if there is some circumstance preventing a | particular, if there is some circumstance preventing a | |||
specific lock | specific lock from being transferred transparently, | |||
from being transferred transparently, | the destination server can allow it to be reclaimed by | |||
the destination server can allow it to be reclaimed, by | implementing a per-fs grace period for the migrated file system. | |||
implementing a | </t> | |||
per-fs grace period for the migrated file system. | <section anchor="SEC11-EFF-lock-sc" numbered="true" toc="default"> | |||
</t> | <name>Security Consideration Related to Reclaiming Lock State after | |||
File System Transitions</name> | ||||
<section title="Security Consideration Related to Reclaiming Lock State af | <t> | |||
ter File System Transitions" | ||||
anchor="SEC11-EFF-lock-sc"> | ||||
<t> | ||||
Although it is possible for a client reclaiming state to misrepresent | Although it is possible for a client reclaiming state to misrepresent | |||
its state, in the same fashion as described in | its state in the same fashion as described in | |||
<xref target="reclaim_security_considerations"/>, most | <xref target="reclaim_security_considerations" format="default"/>, most | |||
implementations providing for such reclamation in the case of | implementations providing for such reclamation in the case of | |||
file system transitions | file system transitions | |||
will have the ability to detect such misrepresentations. This limits | will have the ability to detect such misrepresentations. This limits | |||
the ability of unauthenticated clients to execute denial-of-service | the ability of unauthenticated clients to execute denial-of-service | |||
attacks in these circumstances. Nevertheless, the rules stated in | attacks in these circumstances. Nevertheless, the rules stated in | |||
<xref target="reclaim_security_considerations"/>, regarding principal | <xref target="reclaim_security_considerations" format="default"/> regar | |||
verification for reclaim requests, apply in this situation as well. | ding principal | |||
</t> | verification for reclaim requests apply in this situation as well. | |||
<t> | </t> | |||
<t> | ||||
Typically, implementations that support file system transitions | Typically, implementations that support file system transitions | |||
will have | will have extensive information about the locks | |||
extensive information about the locks | to be transferred. This is because of the following: | |||
to be transferred. This is because: | </t> | |||
<list style="symbols"> | <ul spacing="normal"> | |||
<t> | <li> | |||
Since failure is not involved, there is no need store to locking | Since failure is not involved, there is no need to store locking | |||
information in persistent storage. | information in persistent storage. | |||
</t> | </li> | |||
<t> | <li> | |||
There is no need, as there is in the failure case, to update | There is no need, as there is in the failure case, to update | |||
multiple repositories containing locking state to keep them in | multiple repositories containing locking state to keep them in | |||
sync. Instead, there is a one-time communication of locking | sync. Instead, there is a one-time communication of locking | |||
state from the source to the destination server. | state from the source to the destination server. | |||
</t> | </li> | |||
<t> | <li> | |||
Providing this information avoids potential interference with | Providing this information avoids potential interference with | |||
existing clients using the destination file system, by denying | existing clients using the destination file system by denying | |||
them the ability to obtain new locks during the grace period. | them the ability to obtain new locks during the grace period. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
When such detailed locking information, not necessarily including | When such detailed locking information, not necessarily including | |||
the associated stateids, is available: | the associated stateids, is available: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
It is possible to detect reclaim requests that attempt to | It is possible to detect reclaim requests that attempt to | |||
reclaim locks that did not exist before the transfer, rejecting | reclaim locks that did not exist before the transfer, rejecting | |||
them with NFS4ERR_RECLAIM_BAD (<xref target="err_RECLAIM_BAD"/>). | them with NFS4ERR_RECLAIM_BAD (<xref target="err_RECLAIM_BAD" format= | |||
</t> | "default"/>). | |||
<t> | </li> | |||
<li> | ||||
It is possible when dealing with non-reclaim requests, to determine | It is possible when dealing with non-reclaim requests, to determine | |||
whether they conflict with existing locks, eliminating the need | whether they conflict with existing locks, eliminating the need | |||
to return NFS4ERR_GRACE ((<xref target="err_GRACE"/>) on | to return NFS4ERR_GRACE (<xref target="err_GRACE" format="default"/>) on | |||
non-reclaim requests. | non-reclaim requests. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
It is possible for implementations of grace periods in connection | It is possible for implementations of grace periods in connection | |||
with file system transitions not to have detailed locking | with file system transitions not to have detailed locking | |||
information available at the destination server, in which case | information available at the destination server, in which case, | |||
the security situation is exactly as described in | the security situation is exactly as described in | |||
<xref target="reclaim_security_considerations"/>. | <xref target="reclaim_security_considerations" format="default"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="transferred_lease" | <section anchor="transferred_lease" numbered="true" toc="default"> | |||
title="Leases and File System Transitions"> | <name>Leases and File System Transitions</name> | |||
<t> | <t> | |||
In the case of lease renewal, the client may not be | In the case of lease renewal, the client may not be | |||
submitting requests for a file system that has been transferred | submitting requests for a file system that has been transferred | |||
to another server. This can occur | to another server. This can occur | |||
because of the lease renewal mechanism. The | because of the lease renewal mechanism. The | |||
client renews the lease associated with all file systems | client renews the lease associated with all file systems | |||
when submitting | when submitting | |||
a request on an associated session, regardless of the | a request on an associated session, regardless of the | |||
specific file system being referenced. | specific file system being referenced. | |||
</t> | </t> | |||
<t> | <t> | |||
In order for the client to schedule renewal of its lease | In order for the client to schedule renewal of its lease | |||
where there is locking state that may have been relocated | where there is locking state that may have been relocated | |||
to the new server, the client | to the new server, the client | |||
must find out about lease relocation before that lease | must find out about lease relocation before that lease | |||
expire. To accomplish this, the SEQUENCE operation will | expire. To accomplish this, the SEQUENCE operation will | |||
return the status bit SEQ4_STATUS_LEASE_MOVED | return the status bit SEQ4_STATUS_LEASE_MOVED | |||
if responsibility for any of the renewed locking state | if responsibility for any of the renewed locking state | |||
has been transferred to a new server. This | has been transferred to a new server. This | |||
will continue until the client receives an | will continue until the client receives an | |||
NFS4ERR_MOVED error for each of the file systems for which | NFS4ERR_MOVED error for each of the file systems for which | |||
there has been locking state relocation. | there has been locking state relocation. | |||
</t> | </t> | |||
<t> | <t> | |||
When a client receives an SEQ4_STATUS_LEASE_MOVED indication from | When a client receives an SEQ4_STATUS_LEASE_MOVED indication from | |||
a server, for each file system of the server for which the client | a server, for each file system of the server for which the client | |||
has locking state, the client should perform an operation. | has locking state, the client should perform an operation. | |||
For simplicity, the client may choose to reference | For simplicity, the client may choose to reference | |||
all file systems, but what is important | all file systems, but what is important | |||
is that it must reference all file systems for which there was | is that it must reference all file systems for which there was | |||
locking state where that state has moved. Once the client | locking state where that state has moved. Once the client | |||
receives an NFS4ERR_MOVED error for each such file system, | receives an NFS4ERR_MOVED error for each such file system, | |||
the server will clear the SEQ4_STATUS_LEASE_MOVED indication. | the server will clear the SEQ4_STATUS_LEASE_MOVED indication. | |||
The client can terminate the process of checking file systems | The client can terminate the process of checking file systems | |||
once this indication is cleared (but only if the client | once this indication is cleared (but only if the client | |||
has received a reply for all outstanding SEQUENCE requests | has received a reply for all outstanding SEQUENCE requests | |||
on all sessions it has with the server), since there are no others | on all sessions it has with the server), since there are no others | |||
for which locking state has moved. | for which locking state has moved. | |||
</t> | </t> | |||
<t> | <t> | |||
A client may use GETATTR of the fs_status | A client may use GETATTR of the fs_status | |||
(or fs_locations_info) attribute on all of the file systems | (or fs_locations_info) attribute on all of the file systems | |||
to get absence indications in a single (or a few) request(s), | to get absence indications in a single (or a few) request(s), | |||
since absent file systems will not cause an error in this | since absent file systems will not cause an error in this | |||
context. However, it still must do an operation that | context. However, it still must do an operation that | |||
receives NFS4ERR_MOVED on each file system, in order to clear | receives NFS4ERR_MOVED on each file system, in order to clear | |||
the SEQ4_STATUS_LEASE_MOVED indication. | the SEQ4_STATUS_LEASE_MOVED indication. | |||
</t> | </t> | |||
<t> | <t> | |||
Once the set of file systems with transferred locking state | Once the set of file systems with transferred locking state | |||
has been determined, the client can follow the normal process | has been determined, the client can follow the normal process | |||
to obtain the new server information (through the | to obtain the new server information (through the | |||
fs_locations and fs_locations_info attributes) and perform renewal | fs_locations and fs_locations_info attributes) and perform renewal | |||
of that lease on the new server, unless information in the | of that lease on the new server, unless information in the | |||
fs_locations_info attribute shows that no state could have | fs_locations_info attribute shows that no state could have | |||
been transferred. If the server has not | been transferred. If the server has not | |||
had state transferred to it transparently, the client | had state transferred to it transparently, the client | |||
will receive NFS4ERR_STALE_CLIENTID | will receive NFS4ERR_STALE_CLIENTID | |||
from the new server, | from the new server, | |||
as described above, and the client can then reclaim | as described above, and the client can then reclaim | |||
locks | locks | |||
as is done in the event of server failure. | as is done in the event of server failure. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="transition_lease_time" | <section anchor="transition_lease_time" numbered="true" toc="default"> | |||
title="Transitions and the Lease_time Attribute"> | <name>Transitions and the Lease_time Attribute</name> | |||
<t> | <t> | |||
In order that the client may appropriately manage its lease | In order that the client may appropriately manage its lease | |||
in the case of a file system transition, the destination server must | in the case of a file system transition, the destination server must | |||
establish proper values for the lease_time attribute. | establish proper values for the lease_time attribute. | |||
</t> | </t> | |||
<t> | <t> | |||
When state is transferred transparently, that state | When state is transferred transparently, that state | |||
should include the correct value of the lease_time | should include the correct value of the lease_time | |||
attribute. The lease_time attribute on the destination | attribute. The lease_time attribute on the destination | |||
server must never be less than that on the source, since | server must never be less than that on the source, since | |||
this would result in premature expiration of a lease | this would result in premature expiration of a lease | |||
granted by the source server. Upon transitions in which | granted by the source server. Upon transitions in which | |||
state is transferred transparently, the client is under | state is transferred transparently, the client is under | |||
no obligation to refetch the lease_time attribute and | no obligation to refetch the lease_time attribute and | |||
may continue to use the value | may continue to use the value | |||
previously fetched (on the source server). | previously fetched (on the source server). | |||
</t> | </t> | |||
<t> | <t> | |||
If state has not been transferred transparently, either | If state has not been transferred transparently, either | |||
because the associated servers are shown as having different | because the associated servers are shown as having different | |||
eir_server_scope strings or because the client ID | eir_server_scope strings or because the client ID | |||
is rejected when presented to the new server, | is rejected when presented to the new server, | |||
the client should fetch the value | the client should fetch the value | |||
of lease_time on the new (i.e., destination) server, and | of lease_time on the new (i.e., destination) server, and | |||
use it for subsequent locking requests. However, the server | use it for subsequent locking requests. However, the server | |||
must respect a grace | must respect a grace | |||
period of at least as long as the lease_time on the source | period of at least as long as the lease_time on the source | |||
server, in order to ensure that clients have ample time to | server, in order to ensure that clients have ample time to | |||
reclaim their lock before potentially conflicting | reclaim their lock before potentially conflicting | |||
non-reclaimed locks are granted. | non-reclaimed locks are granted. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
</section> | </section> | |||
<section title="Transferring State upon Migration" | <section anchor="SEC11-trans-locking" numbered="true" toc="default"> | |||
anchor="SEC11-trans-locking"> | <name>Transferring State upon Migration</name> | |||
<t> | <t> | |||
When the transition is a result of a server-initiated decision | When the transition is a result of a server-initiated decision | |||
to transition access and the source and destination servers have | to transition access, and the source and destination servers have | |||
implemented appropriate co-operation, it is possible to: | implemented appropriate cooperation, it is possible to do the following: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Transfer locking state from the source to the destination | Transfer locking state from the source to the destination | |||
server, in a fashion similar to that provided by Transparent State | server in a fashion similar to that provided by Transparent State | |||
Migration in NFSv4.0, as described in <xref target="RFC7931"/>. | Migration in NFSv4.0, as described in <xref target="RFC7931" format="def | |||
Server responsibilities are described in | ault"/>. | |||
<xref target="SEC11-XS-lock"/>. | Server responsibilities are described in <xref target="SEC11-XS-lock" fo | |||
rmat="default"/>. | ||||
</t> | </li> | |||
<t> | <li> | |||
Transfer session state from the source to the destination | Transfer session state from the source to the destination | |||
server. Server responsibilities in effecting such a | server. Server responsibilities in effecting such a | |||
transfer are described in | transfer are described in <xref target="SEC11-XS-session" format="defaul | |||
<xref target="SEC11-XS-session"/>. | t"/>. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The means by which the client determines which of these transfer | The means by which the client determines which of these transfer | |||
events has occurred are described in | events has occurred are described in | |||
<xref target="SEC11-trans-client"/>. | <xref target="SEC11-trans-client" format="default"/>. | |||
</t> | </t> | |||
<section title="Transparent State Migration and pNFS" | <section anchor="V41p-pnfs" numbered="true" toc="default"> | |||
anchor="V41p-pnfs"> | <name>Transparent State Migration and pNFS</name> | |||
<t> | <t> | |||
When pNFS is involved, the protocol is capable of supporting: | When pNFS is involved, the protocol is capable of supporting: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Migration of the Metadata Server (MDS), leaving the Data | Migration of the Metadata Server (MDS), leaving the Data | |||
Servers (DS's) in place. | Servers (DSs) in place. | |||
</t> | </li> | |||
<t> | <li> | |||
Migration of the file system as a whole, including the MDS | Migration of the file system as a whole, including the MDS | |||
and associated DS's. | and associated DSs. | |||
</t> | </li> | |||
<t> | <li> | |||
Replacement of one DS by another. | Replacement of one DS by another. | |||
</t> | </li> | |||
<t> | <li> | |||
Migration of a pNFS file system to one in which | Migration of a pNFS file system to one in which pNFS is not used. | |||
pNFS is not used. | </li> | |||
</t> | <li> | |||
<t> | ||||
Migration of a file system not using pNFS to one in which | Migration of a file system not using pNFS to one in which | |||
layouts are available. | layouts are available. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | Note that migration, per se, is only involved in the transfer of | |||
Note that migration per se is only involved in the transfer of | the MDS function. Although the servicing of a layout may be | |||
the MDS function. Although the servicing of a layout may be | ||||
transferred from one data server to another, this not done using | transferred from one data server to another, this not done using | |||
the file system location attributes. The MDS can effect such | the file system location attributes. The MDS can effect such | |||
transfers by recalling/revoking existing layouts and granting new | transfers by recalling or revoking existing layouts and granting new | |||
ones on a different data server. | ones on a different data server. | |||
</t> | </t> | |||
<t> | <t> | |||
Migration of the MDS function is directly supported by | Migration of the MDS function is directly supported by | |||
Transparent State Migration. Layout state will normally be | Transparent State Migration. Layout state will normally be | |||
transparently transferred, just as other state is. | transparently transferred, just as other state is. | |||
As a result, Transparent State Migration provides a framework in | As a result, Transparent State Migration provides a framework in | |||
which, given appropriate inter-MDS data transfer, one MDS can | which, given appropriate inter-MDS data transfer, one MDS can | |||
be substituted for another. | be substituted for another. | |||
</t> | </t> | |||
<t> | <t> | |||
Migration of the file system function as a whole | Migration of the file system function as a whole can be accomplished by | |||
can be accomplished by | ||||
recalling all layouts as part of the initial phase of the | recalling all layouts as part of the initial phase of the | |||
migration process. As a result, IO will be done through the | migration process. As a result, I/O will be done through the | |||
MDS during the migration process, and new layouts can be granted | MDS during the migration process, and new layouts can be granted | |||
once the client is interacting with the new MDS. An MDS can | once the client is interacting with the new MDS. An MDS can | |||
also effect this sort of transition by revoking all layouts | also effect this sort of transition by revoking all layouts | |||
as part of Transparent State Migration, as long as the client is | as part of Transparent State Migration, as long as the client is | |||
notified about the loss of locking state. | notified about the loss of locking state. | |||
</t> | </t> | |||
<t> | <t> | |||
In order to allow migration to a file system on which pNFS is | In order to allow migration to a file system on which pNFS is | |||
not supported, clients need to be prepared for a situation in | not supported, clients need to be prepared for a situation in | |||
which layouts are not available or | which layouts are not available or supported on the destination file | |||
supported on the destination file | system and so direct I/O requests to the destination | |||
system and so direct IO requests to the destination | ||||
server, rather than depending on layouts being available. | server, rather than depending on layouts being available. | |||
</t> | </t> | |||
<t> | <t> | |||
Replacement of one DS by another is not addressed by migration as | Replacement of one DS by another is not addressed by migration as | |||
such but can be effected by an MDS recalling layouts for the DS | such but can be effected by an MDS recalling layouts for the DS | |||
to be replaced and issuing new ones to be served by the | to be replaced and issuing new ones to be served by the | |||
successor DS. | successor DS. | |||
</t> | </t> | |||
<t> | <t> | |||
Migration may transfer a file system from a server which does | Migration may transfer a file system from a server that does | |||
not support pNFS to one which does. In order to properly adapt | not support pNFS to one that does. In order to properly adapt | |||
to this situation, clients which support pNFS, but function | to this situation, clients that support pNFS, but function | |||
adequately in its absence should check for pNFS support when | adequately in its absence, should check for pNFS support when | |||
a file system is migrated and be prepared to use pNFS when | a file system is migrated and be prepared to use pNFS when | |||
support is available on the destination. | support is available on the destination. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | ||||
</section> | <section anchor="SEC11-trans-client" numbered="true" toc="default"> | |||
<section title="Client Responsibilities when Access is Transitioned" | <name>Client Responsibilities When Access Is Transitioned</name> | |||
anchor="SEC11-trans-client"> | <t> | |||
<t> | ||||
For a client to respond to an access transition, it must become | For a client to respond to an access transition, it must become | |||
aware of it. The ways in which this can happen are discussed | aware of it. The ways in which this can happen are discussed | |||
in <xref target="V41c-clrecov"/> which discusses indications | in <xref target="V41c-clrecov" format="default"/>, which discusses indicat ions | |||
that a specific file system access path has transitioned as well as | that a specific file system access path has transitioned as well as | |||
situations in which additional activity is necessary to | situations in which additional activity is necessary to | |||
determine the set of file systems that have been migrated. | determine the set of file systems that have been migrated. | |||
<xref target="V41c-migrdisc"/> goes on to complete the discussion | <xref target="V41c-migrdisc" format="default"/> goes on to complete the di scussion | |||
of how the set of migrated file systems might be determined. | of how the set of migrated file systems might be determined. | |||
Sections <xref target="V41c-omoved" format="counter"/> through | Sections <xref target="V41c-omoved" format="counter"/> through | |||
<xref target="V41c-ssnwas" format="counter"/> | <xref target="V41c-ssnwas" format="counter"/> | |||
discuss how the client should deal with | discuss how the client should deal with | |||
each transition it becomes aware of, either directly or as a | each transition it becomes aware of, either directly or as a | |||
result of migration discovery. | result of migration discovery. | |||
</t> | </t> | |||
<t> | <t> | |||
The following terms are used to describe client activities: | The following terms are used to describe client activities: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
"Transition recovery" refers to the process of restoring access | "Transition recovery" refers to the process of restoring access | |||
to a file system on which NFS4ERR_MOVED was received. | to a file system on which NFS4ERR_MOVED was received. | |||
</t> | </li> | |||
<t> | <li> | |||
"Migration recovery" to that subset of transition recovery | "Migration recovery" refers to that subset of transition recovery | |||
which applies when the file system has migrated to a different | that applies when the file system has migrated to a different | |||
replica. | replica. | |||
</t> | </li> | |||
<t> | <li> | |||
"Migration discovery" refers to the process of determining which | "Migration discovery" refers to the process of determining which | |||
file system(s) have been migrated. It is necessary to | file system(s) have been migrated. It is necessary to avoid a situation | |||
avoid a situation in | in | |||
which leases could expire when a file system is not accessed for | which leases could expire when a file system is not accessed for | |||
a long period of time, since a client unaware of the migration | a long period of time, since a client unaware of the migration | |||
might be referencing an unmigrated file system and not renewing | might be referencing an unmigrated file system and not renewing | |||
the lease associated with the migrated file system. | the lease associated with the migrated file system. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <section anchor="V41c-clrecov" numbered="true" toc="default"> | |||
<section title="Client Transition Notifications" | <name>Client Transition Notifications</name> | |||
anchor="V41c-clrecov"> | <t> | |||
<t> | ||||
When there is a change in the network access | When there is a change in the network access | |||
path which a client is to use to access a file | path that a client is to use to access a file system, there | |||
system, there | are a number of related status indications with which clients | |||
are a number of | ||||
related status indications with which clients | ||||
need to deal: | need to deal: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
If an attempt is made to use or return a filehandle | If an attempt is made to use or return a filehandle | |||
within a file system that is no longer accessible at the | within a file system that is no longer accessible at the | |||
address previously used to access it, the | address previously used to access it, the | |||
error NFS4ERR_MOVED is returned. | error NFS4ERR_MOVED is returned. | |||
<vspace blankLines='1' /> | </t> | |||
Exceptions are made to allow such file handles to be used | <t> | |||
Exceptions are made to allow such filehandles to be used | ||||
when interrogating a file system location attribute. | when interrogating a file system location attribute. | |||
This enables a | This enables a client to determine | |||
client to determine | ||||
a new replica's location or a new network access path. | a new replica's location or a new network access path. | |||
<vspace blankLines='1' /> | </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> | |||
<t> | </li> | |||
Whenever a SEQUENCE operation is sent by a client to | <li> | |||
a server which generated state held on that client which | <t> | |||
is associated with a file system that is no longer accessible | Whenever a client sends a SEQUENCE operation to a server that | |||
on the server at which it was previously available, the response | generated state held on that client and associated with a | |||
will contain a | file system no longer accessible on that server, the response will contain | |||
lease-migrated indication, with the | the status bit SEQ4_STATUS_LEASE_MOVED, indicating that there has | |||
SEQ4_STATUS_LEASE_MOVED status bit being set. | been a lease migration. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
This condition continues until the client acknowledges | This condition continues until the client acknowledges | |||
the notification by fetching a file system | the notification by fetching a file system location attribute for the | |||
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 system needs to be fetched | attribute for all migrated file systems needs to be fetched | |||
in order to clear the condition. | in order to clear the condition. Even after the condition is cleared, | |||
Even after the condition is cleared, the | the | |||
client needs to respond by using the location information | client needs to respond by using the location information | |||
to access the file system at its new location | to access the file system at its new location | |||
to ensure that leases are | to ensure that leases are not needlessly expired. | |||
not needlessly expired. | </t> | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | Unlike NFSv4.0, in which the corresponding | |||
Unlike the case of NFSv4.0, in which the corresponding | ||||
conditions are both errors and thus mutually exclusive, | conditions are both errors and thus mutually exclusive, | |||
in NFSv4.1 the client can, | in NFSv4.1 the client can, | |||
and often will, receive both indications on the same | and often will, receive both indications on the same | |||
request. As a result, implementations need to address the | request. As a result, implementations need to address the | |||
question of how to co-ordinate | question of how to coordinate | |||
the necessary recovery actions when both indications | the necessary recovery actions when both indications | |||
arrive in the response to the same request. It should be noted | arrive in the response to the same request. It should be noted | |||
that when processing an NFSv4 COMPOUND, the server | that when processing an NFSv4 COMPOUND, the server | |||
will normally decide | will normally decide | |||
whether SEQ4_STATUS_LEASE_MOVED is to be set before | whether SEQ4_STATUS_LEASE_MOVED is to be set before | |||
it determines which file system will be referenced or whether | it determines which file system will be referenced or whether | |||
NFS4ERR_MOVED is to be returned. | NFS4ERR_MOVED is to be returned. | |||
</t> | </t> | |||
<t> | <t> | |||
Since these indications are not mutually exclusive in NFSv4.1, | Since these indications are not mutually exclusive in NFSv4.1, | |||
the following combinations are possible results when a COMPOUND | the following combinations are possible results when a COMPOUND | |||
is issued: | is issued: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
The COMPOUND status | The COMPOUND status | |||
is NFS4ERR_MOVED and SEQ4_STATUS_LEASE_MOVED is asserted. | is NFS4ERR_MOVED, and SEQ4_STATUS_LEASE_MOVED is asserted. | |||
<vspace blankLines='1'/> | </t> | |||
<t> | ||||
In this case, transition recovery is required. While it is | In this case, transition recovery is required. While it is | |||
possible that migration discovery is needed in addition, it | possible that migration discovery is needed in addition, it | |||
is likely that only the accessed file system has transitioned. | is likely that only the accessed file system has transitioned. | |||
In any case, because addressing NFS4ERR_MOVED is necessary to | In any case, because addressing NFS4ERR_MOVED is necessary to | |||
allow the rejected requests to be processed on the target, | allow the rejected requests to be processed on the target, | |||
dealing with it will typically have priority over | dealing with it will typically have priority over | |||
migration discovery. | migration discovery. | |||
</t> | ||||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
The COMPOUND status | The COMPOUND status | |||
is NFS4ERR_MOVED and SEQ4_STATUS_LEASE_MOVED is clear. | is NFS4ERR_MOVED, and SEQ4_STATUS_LEASE_MOVED is clear. | |||
<vspace blankLines='1'/> | </t> | |||
<t> | ||||
In this case, transition recovery is also required. It is | In this case, transition recovery is also required. It is | |||
clear that migration discovery is not needed to find | clear that migration discovery is not needed to find | |||
file systems that have been migrated other that the one | file systems that have been migrated other than the one | |||
returning NFS4ERR_MOVED. Cases in which this | returning NFS4ERR_MOVED. Cases in which this | |||
result can arise include a referral or a migration for which | result can arise include a referral or a migration for which | |||
there is no associated locking state. This can also arise in | there is no associated locking state. This can also arise in | |||
cases in which an access path transition | cases in which an access path transition | |||
other than migration occurs within the same server. In such a | other than migration occurs within the same server. In such a | |||
case, there is no need to set SEQ4_STATUS_LEASE_MOVED, since | case, there is no need to set SEQ4_STATUS_LEASE_MOVED, since | |||
the lease remains associated with the current server even though | the lease remains associated with the current server even though | |||
the access path has changed. | the access path has changed. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
The COMPOUND status | The COMPOUND status | |||
is not NFS4ERR_MOVED and SEQ4_STATUS_LEASE_MOVED is asserted. | is not NFS4ERR_MOVED, and SEQ4_STATUS_LEASE_MOVED is asserted. | |||
<vspace blankLines='1'/> | </t> | |||
<t> | ||||
In this case, no transition recovery activity is required on | In this case, no transition recovery activity is required on | |||
the file system(s) accessed by the request. | the file system(s) accessed by the request. However, to prevent avoid | |||
However, to prevent avoidable | able | |||
lease expiration, migration discovery needs to be done | lease expiration, migration discovery needs to be done. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
The COMPOUND status | The COMPOUND status | |||
is not NFS4ERR_MOVED and SEQ4_STATUS_LEASE_MOVED is clear. | is not NFS4ERR_MOVED, and SEQ4_STATUS_LEASE_MOVED is clear. | |||
<vspace blankLines='1'/> | </t> | |||
<t> | ||||
In this case, neither transition-related activity nor migration | In this case, neither transition-related activity nor migration | |||
discovery is required. | discovery is required. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ul> | |||
<t> | <t> | |||
Note that the specified actions only need to be taken if they are | Note that the specified actions only need to be taken if they are | |||
not already going on. For example, when NFS4ERR_MOVED is received | not already going on. For example, when NFS4ERR_MOVED is received | |||
when accessing a file system | while accessing a file system for which transition recovery is already oc | |||
for which transition recovery already going on, the client | curring, the client | |||
merely waits for | merely waits for that recovery to be completed, while the receipt of | |||
that recovery to be completed while the receipt of | the SEQ4_STATUS_LEASE_MOVED indication only | |||
SEQ4_STATUS_LEASE_MOVED indication only | ||||
needs to initiate migration discovery for a server if such | needs to initiate migration discovery for a server if such | |||
discovery is not already underway for that server. | discovery is not already underway for that server. | |||
</t> | </t> | |||
<t> | <t> | |||
The fact that a lease-migrated condition does not result in | The fact that a lease-migrated condition does not result in | |||
an error in NFSv4.1 has a number of important consequences. | an error in NFSv4.1 has a number of important consequences. | |||
In addition to the fact, discussed above, that the two | In addition to the fact that the two | |||
indications are not mutually exclusive, there are number of | indications are not mutually exclusive, as discussed above, there are nu | |||
mber of | ||||
issues that are important in considering implementation of | issues that are important in considering implementation of | |||
migration discovery, as discussed in | migration discovery, as discussed in | |||
<xref target="V41c-migrdisc"/>. | <xref target="V41c-migrdisc" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
Because SEQ4_STATUS_LEASE_MOVED is not an | Because SEQ4_STATUS_LEASE_MOVED is not an error condition, it is possibl | |||
error condition", it is possible | e | |||
for file systems whose access paths have not changed to be | for file systems whose access paths have not changed to be | |||
successfully accessed on a given server even though recovery | successfully accessed on a given server even though recovery | |||
is necessary for other file systems on the same server. As | is necessary for other file systems on the same server. As | |||
a result, access can go on while, | a result, access can take place while: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
The migration discovery process is going on for that server. | <li> | |||
</t> | The migration discovery process is happening for that server. | |||
<t> | </li> | |||
The transition recovery process is going on for other | <li> | |||
The transition recovery process is happening for other | ||||
file systems connected to that server. | file systems connected to that server. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section anchor="V41c-migrdisc" numbered="true" toc="default"> | |||
<section title="Performing Migration Discovery" | <name>Performing Migration Discovery</name> | |||
anchor="V41c-migrdisc"> | <t> | |||
<t> | ||||
Migration discovery can be performed in the same context as | Migration discovery can be performed in the same context as | |||
transition recovery, allowing recovery for each migrated file | transition recovery, allowing recovery for each migrated file | |||
system to be invoked as it is discovered. Alternatively, it may | system to be invoked as it is discovered. Alternatively, it may | |||
be done in a separate migration discovery thread, allowing | be done in a separate migration discovery thread, allowing | |||
migration discovery to be done in parallel with | migration discovery to be done in parallel with | |||
one or more instances | one or more instances of transition recovery. | |||
of transition recovery. | </t> | |||
</t> | <t> | |||
<t> | ||||
In either case, because the lease-migrated indication | In either case, because the lease-migrated indication | |||
does not result in an error. other access to file systems on the | does not result in an error, other access to file systems on the | |||
server can proceed normally, with the possibility that further | server can proceed normally, with the possibility that further | |||
such indications will be received, raising the issue of how | such indications will be received, raising the issue of how | |||
such indications are to be dealt with. In general, | such indications are to be dealt with. In general: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
No action needs to be taken for such indications received by any | No action needs to be taken for such indications received by any | |||
threads performing migration discovery, since continuation of that | threads performing migration discovery, since continuation of that | |||
work will address the issue. | work will address the issue. | |||
</t> | </li> | |||
<t> | <li> | |||
In other cases in which migration discovery is currently | In other cases in which migration discovery is currently being perform | |||
being performed, | ed, | |||
nothing further needs to be done to respond to such lease | nothing further needs to be done to respond to such lease | |||
migration indications, as long as one can be | migration indications, as long as one can be certain that the migratio | |||
certain that the migration | n | |||
discovery process would deal with those indications. See below | discovery process would deal with those indications. See below for det | |||
for details. | ails. | |||
</t> | </li> | |||
<t> | <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 | appropriate response is to initiate or otherwise provide for the | |||
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. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <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 i f | |||
the migration discovery process is not able to respond to | the migration discovery process is not able to respond to | |||
the discovery of additional | the discovery of additional migrating file | |||
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 | may occur at any time, and because a SEQ4_STATUS_LEASE_MOVED indication m | |||
at any time, and because a LEASE_MOVED indication may reflect | ay reflect | |||
the situation in effect a considerable time before the indication | the situation in effect a considerable time before the indication | |||
is received, | is received, special care needs to be taken to ensure that SEQ4_STATUS_LE | |||
special care needs to be taken to ensure that LEASE_MOVED | ASE_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: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
non-operation, in which migration discovery is not being | <li> | |||
performed | Non-operation, in which migration discovery is not being | |||
</t> | performed. | |||
<t> | </li> | |||
normal operation, in which there is an ongoing scan for | <li> | |||
Normal operation, in which there is an ongoing scan for | ||||
migrated file systems. | migrated file systems. | |||
</t> | </li> | |||
<t> | <li> | |||
completion/verification of migration discovery processing, | Completion/verification of migration discovery processing, | |||
in which the possible completion of migration discovery | in which the possible completion of migration discovery | |||
processing needs to be verified. | processing needs to be verified. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Given that framework, migration discovery processing would proceed | Given that framework, migration discovery processing would proceed | |||
as follows. | as follows: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
While in the normal-operation state, the thread performing | While in the normal-operation state, the thread performing | |||
discovery would fetch, for | discovery would fetch, for | |||
successive file systems known to the client on the server being | successive file systems known to the client on the server being | |||
worked on, a file system location | worked on, a file system location attribute plus the fs_status attribu | |||
attribute plus the fs_status attribute. | te. | |||
</t> | </li> | |||
<t> | <li> | |||
If the fs_status attribute indicates that the file system | If the fs_status attribute indicates that the file system | |||
is a migrated one (i.e. fss_absent is true and | is a migrated one (i.e., fss_absent is true, and | |||
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 the file systems contributing to the | cleared one of the file systems contributing to the | |||
lease-migrated indication. | lease-migrated indication. | |||
</t> | </li> | |||
<t> | <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 | the lease-migrated indication has been cleared, and so it enters the | |||
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. | |||
</t> | </li> | |||
<t> | <li> | |||
When the discovery process is in the | When the discovery process is in the completion/verification state, | |||
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 | indications is used when the request completes, as described below. | |||
described below. | </li> | |||
</t> | </ul> | |||
</list> | <t> | |||
</t> | When the request used in the completion/verification state completes: | |||
<t> | </t> | |||
When the request used in the completion/verification state | <ul spacing="normal"> | |||
completes: | <li> | |||
<list style ='symbols'> | ||||
<t> | ||||
If a lease-migrated indication is returned, the discovery | If a lease-migrated indication is returned, the discovery | |||
continues normally. Note that this is so | continues normally. Note that this is so even if all file systems | |||
even if all file systems | have been traversed, since new migrations could have occurred | |||
have traversed, since new migrations could have occurred | while the process was going on. | |||
while the process | </li> | |||
was going on. | <li> | |||
</t> | ||||
<t> | ||||
Otherwise, if there is any record that other requests saw a | Otherwise, if there is any record that other requests saw a | |||
lease-migrated indication while the request was going on, | lease-migrated indication while the request was occurring, | |||
that record is cleared and the | that record is cleared, and the verification request is retried. The d | |||
verification request retried. The discovery | iscovery | |||
process remains in completion/verification state. | process remains in the completion/verification state. | |||
</t> | </li> | |||
<t> | <li> | |||
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 indication will trigger a new migration discovery | lease-migrated indications will trigger a new migration discovery | |||
process. | process. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
</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_MOVE D | |||
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 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 | |||
may mean that a lock is revoked unexpectedly. Clients should be aware | may mean that a lock is revoked unexpectedly. Clients should be aware | |||
of this possibility. | of this possibility. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Overview of Client Response to NFS4ERR_MOVED" | <section anchor="V41c-omoved" numbered="true" toc="default"> | |||
anchor="V41c-omoved"> | <name>Overview of Client Response to NFS4ERR_MOVED</name> | |||
<t> | <t> | |||
This section outlines a way in which a client that receives | This section outlines a way in which a client that receives | |||
NFS4ERR_MOVED can effect transition recovery by using a new | NFS4ERR_MOVED can effect transition recovery by using a new | |||
server or server endpoint | server or server endpoint | |||
if one is available. As part of that process, it will | if one is available. As part of that process, it will | |||
determine: | determine: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Whether the NFS4ERR_MOVED indicates migration has occurred, | Whether the NFS4ERR_MOVED indicates migration has occurred, | |||
or whether it indicates another sort of file system | or whether it indicates another sort of file system | |||
access transition as discussed | access transition as discussed | |||
in <xref target="SEC11-nwa"/> above. | in <xref target="SEC11-nwa" format="default"/> above. | |||
</t> | </li> | |||
<t> | <li> | |||
In the case of migration, whether Transparent State | In the case of migration, whether Transparent State | |||
Migration has occurred. | Migration has occurred. | |||
</t> | </li> | |||
<t> | <li> | |||
Whether any state has been lost during the process of | Whether any state has been lost during the process of | |||
Transparent State Migration. | Transparent State Migration. | |||
</t> | </li> | |||
<t> | <li> | |||
Whether sessions have been transferred as part of Transparent | Whether sessions have been transferred as part of Transparent | |||
State Migration. | State Migration. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <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: | |||
<list style="numbers"> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<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 use 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 that | 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 | file system and can share locking state with it). | |||
locking state with it). | </li> | |||
</t> | <li> | |||
<t> | ||||
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 | |||
current location element is server-trunkable with that | current location element is server-trunkable with that | |||
used to access the file system when access | used to access the file system when access | |||
was terminated by receiving NFS4ERR_MOVED. | was terminated by receiving NFS4ERR_MOVED. | |||
If it is, then migration has not occurred. In that case, the | If it is, then migration has not occurred. In that case, the | |||
transition is | transition is | |||
dealt with, at least initially, as one involving continued | dealt with, at least initially, as one involving continued | |||
access to the same file system on the same server through | access to the same file system on the same server through | |||
a new network address. | a new network address. | |||
</t> | </li> | |||
<t> | <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"/> 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"/> below | <xref target="V41c-ssnwas" format="default"/> below | |||
in the case of a network | in the case of a network address transfer without migration. | |||
address transfer without migration. | </li> | |||
</t> | <li> | |||
<t> | Verifying the trunking relationship assumed in step | |||
Verification of the trunking relationship assumed in step | 2 as discussed in <xref target="PREP-trunk-verify" format="default"/>. | |||
2 as discussed in <xref target="PREP-trunk-verify"/>. | 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 fail with | the initial determination of network address shift (without | |||
the result that an initial determination that a network address | migration) and instead determine that migration had occurred. | |||
shift (without migration) has occurred may be invalidated and | There is no need to redo | |||
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. | |||
</t> | </li> | |||
<t> | <li> | |||
Obtaining access to existing locking state and/or | Obtaining access to existing locking state and/or | |||
reobtaining 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"/> | can be done as described below in <xref target="V41c-ssmig" format="de fault"/> | |||
in the case of migration or as described in | in the case of migration or as described in | |||
<xref target="V41c-ssnwas"/> | <xref target="V41c-ssnwas" format="default"/> | |||
in the case of a network | in the case of a network address transfer without migration. | |||
address transfer without migration. | </li> | |||
</ol> | ||||
</t> | <t> | |||
</list> | ||||
</t> | ||||
<t> | ||||
Once the initial address has been determined, clients are free | Once the initial address has been determined, clients are free | |||
to apply an abbreviated process to find additional addresses | to apply an abbreviated process to find additional addresses | |||
trunkable with it (clients may seek session-trunkable or | trunkable with it (clients may seek session-trunkable or | |||
server-trunkable addresses depending on whether they support | server-trunkable addresses depending on whether they support | |||
clientid trunking). During this later phase of the process, | client ID trunking). During this later phase of the process, | |||
further location entries are examined using the abbreviated | further location entries are examined using the abbreviated | |||
procedure specified below: | procedure specified below: | |||
<list style="format %C:"> | </t> | |||
<t> | <ol spacing="normal" type="%C:"> | |||
<li> | ||||
Before the EXCHANGE_ID, the fs name of the location | Before the EXCHANGE_ID, the fs name of the location | |||
entry is examined and if it | entry is examined, and if it | |||
does not match that currently being used, the entry is ignored. | does not match that currently being used, the entry is ignored. | |||
otherwise, one proceeds as specified by step 1 above. | Otherwise, one proceeds as specified by step 1 above. | |||
</t> | </li> | |||
<t> | <li> | |||
In the case that the network address is session-trunkable with one | In the case that the network address is session-trunkable with one | |||
used previously a BIND_CONN_TO_SESSION is used to access that | used previously, a BIND_CONN_TO_SESSION is used to access that | |||
session using the new network address. Otherwise, or if the bind | session using the new network address. Otherwise, or if the bind | |||
operation fails, a CREATE_SESSION is done. | operation fails, a CREATE_SESSION is done. | |||
</t> | </li> | |||
<t> | <li> | |||
The verification procedure referred to in step 4 above is | The verification procedure referred to in step 4 above is | |||
used. However, if it fails, the entry is ignored and the next | used. However, if it fails, the entry is ignored and the next | |||
available entry is used. | available entry is used. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | </section> | |||
</section> | <section anchor="V41c-ssmig" numbered="true" toc="default"> | |||
<name>Obtaining Access to Sessions and State after Migration</name> | ||||
<section title="Obtaining Access to Sessions and State after Migration" | <t> | |||
anchor="V41c-ssmig"> | ||||
<t> | ||||
In the event that migration has occurred, migration recovery | In the event that migration has occurred, migration recovery | |||
will involve determining | will involve determining whether Transparent State Migration has | |||
whether Transparent State Migration has | ||||
occurred. This decision is made based on the client ID returned | occurred. This decision is made based on the client ID returned | |||
by the EXCHANGE_ID | by the EXCHANGE_ID and the reported confirmation status. | |||
and the reported | </t> | |||
confirmation status. | <ul spacing="normal"> | |||
<list style ='symbols'> | <li> | |||
<t> | ||||
If the client ID is an unconfirmed client ID not previously known | If the client ID is an unconfirmed client ID not previously known | |||
to the client, then Transparent State | to the client, then Transparent State Migration has not occurred. | |||
Migration has not occurred. | </li> | |||
</t> | <li> | |||
<t> | ||||
If the client ID is a confirmed client ID previously known | If the client ID is a confirmed client ID previously known | |||
to the client, then any transferred state would have been | to the client, then any transferred state would have been | |||
merged with an existing client ID representing the client to the | merged with an existing client ID representing the client to the | |||
destination server. In this state merger case, Transparent | destination server. In this state merger case, Transparent | |||
State Migration might | State Migration might | |||
or might not have occurred and a determination as to whether | or might not have occurred, and a determination as to whether | |||
it has occurred is deferred until sessions are established | it has occurred is deferred until sessions are established | |||
and the client is ready to begin state recovery. | and the client is ready to begin state recovery. | |||
</t> | </li> | |||
<t> | <li> | |||
If the client ID is a confirmed client ID not previously known | If the client ID is a confirmed client ID not previously known | |||
to the client, then the client can conclude that the | to the client, then the client can conclude that the | |||
client ID was transferred as part of Transparent State Migration. | client ID was transferred as part of Transparent State Migration. | |||
In this transferred client ID case, Transparent State Migration | In this transferred client ID case, Transparent State Migration | |||
has occurred although some state might have been lost. | has occurred, although some state might have been lost. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Once the client ID has been obtained, it is necessary to | Once the client ID has been obtained, it is necessary to | |||
obtain access to sessions to continue communication with the | obtain access to sessions to continue communication with the | |||
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> | |||
<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 | |||
locking, the destination server needs to implement a per-fs grace | locking, the destination server needs to implement a per-fs grace | |||
period in all cases in which lock state was lost, including | period in all cases in which lock state was lost, including | |||
those in which Transparent State Migration was not | those in which Transparent State Migration was not | |||
implemented. Each client for which there was a transfer of locking | implemented. Each client for which there was a transfer of locking | |||
state to the new server will have the duration of the grace period | state to the new server will have the duration of the grace period | |||
to reclaim its locks, from the time its locks were transferred. | to reclaim its locks, from the time its locks were transferred. | |||
</t> | </t> | |||
<t> | <t> | |||
Clients need to deal with the following cases: | Clients need to deal with the following cases: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
In the state merger case, it is possible that the server | In the state merger case, it is possible that the server | |||
has not attempted Transparent State Migration, | has not attempted Transparent State Migration, | |||
in which case state may have been | in which case state may have been | |||
lost without it being reflected in the SEQ4_STATUS bits. | lost without it being reflected in the SEQ4_STATUS bits. | |||
To determine whether this has happened, the client can use | To determine whether this has happened, the client can use | |||
TEST_STATEID to check whether the stateids created on the | TEST_STATEID to check whether the stateids created on the | |||
source server are still accessible on the destination server. | source server are still accessible on the destination server. | |||
Once a single stateid is found to have been successfully | Once a single stateid is found to have been successfully | |||
transferred, the client can conclude that Transparent State | transferred, the client can conclude that Transparent State | |||
Migration was begun and any failure to transport all of the | Migration was begun, and any failure to transport all of the | |||
stateids will be reflected in the SEQ4_STATUS bits. Otherwise, | stateids will be reflected in the SEQ4_STATUS bits. Otherwise, | |||
Transparent State Migration has not occurred. | Transparent State Migration has not occurred. | |||
</t> | </li> | |||
<t> | <li> | |||
In a case in which Transparent State Migration has not | In a case in which Transparent State Migration has not | |||
occurred, the client can use the per-fs grace period provided | occurred, the client can use the per-fs grace period provided | |||
by the destination server to reclaim locks that were held on | by the destination server to reclaim locks that were held on | |||
the source server. | the source server. | |||
</t> | </li> | |||
<t> | <li> | |||
In a case in which Transparent State Migration has | In a case in which Transparent State Migration has | |||
occurred, and no lock state was lost (as shown by SEQ4_STATUS | occurred, and no lock state was lost (as shown by SEQ4_STATUS | |||
flags), no lock reclaim is necessary. | flags), no lock reclaim is necessary. | |||
</t> | </li> | |||
<t> | <li> | |||
In a case in which Transparent State Migration has | In a case in which Transparent State Migration has | |||
occurred, and some lock state was lost (as shown by SEQ4_STATUS | occurred, and some lock state was lost (as shown by SEQ4_STATUS | |||
flags), existing stateids need to be checked for validity | flags), existing stateids need to be checked for validity | |||
using TEST_STATEID, and reclaim used to re-establish any that | using TEST_STATEID, and reclaim used to re-establish any that | |||
were not transferred. | were not transferred. | |||
</li> | ||||
</t> | </ul> | |||
</list> | <t> | |||
</t> | ||||
<t> | ||||
For all of the cases above, RECLAIM_COMPLETE with an rca_one_fs | For all of the cases above, RECLAIM_COMPLETE with an rca_one_fs | |||
value of TRUE needs to be done before | value of TRUE needs to be done before | |||
normal use of the file system including obtaining new locks for the | normal use of the file system, including obtaining new locks for the | |||
file system. This applies even if no locks were lost and there | file system. This applies even if no locks were lost and there | |||
was no need for any to be reclaimed. | was no need for any to be reclaimed. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section anchor="V41c-ssnwas" numbered="true" toc="default"> | |||
<section title="Obtaining Access to Sessions and State after Network Address | <name>Obtaining Access to Sessions and State after Network Address Tra | |||
Transfer" | nsfer</name> | |||
anchor="V41c-ssnwas"> | <t> | |||
<t> | ||||
The case in which there is a transfer to a new network | The case in which there is a transfer to a new network | |||
address without migration is similar to that described | address without migration is similar to that described | |||
in <xref target="V41c-ssmig"/> above in that there is a need to | in <xref target="V41c-ssmig" format="default"/> above in that there is a need to | |||
obtain access to needed sessions and locking state. However, | obtain access to needed sessions and locking state. However, | |||
the details are simpler and will vary depending on the | the details are simpler and will vary depending on the | |||
type of trunking between the address receiving | type of trunking between the address receiving | |||
NFS4ERR_MOVED and that to which the transfer is to be made | NFS4ERR_MOVED and that to which the transfer is to be made. | |||
</t> | </t> | |||
<t> | <t> | |||
To make a session available for use, a BIND_CONN_TO_SESSION | To make a session available for use, a BIND_CONN_TO_SESSION | |||
should be used to obtain access to the session previously | should be used to obtain access to the session previously | |||
in use. Only if this fails, should a CREATE_SESSION be done. | in use. Only if this fails, should a CREATE_SESSION be done. | |||
While this procedure mirrors that in <xref target="V41c-ssmig"/> | While this procedure mirrors that in <xref target="V41c-ssmig" format="d efault"/> | |||
above, | above, | |||
there is an important difference in that preservation of the | there is an important difference in that preservation of the | |||
session is not purely optional but depends on the type of | session is not purely optional but depends on the type of | |||
trunking. | trunking. | |||
</t> | </t> | |||
<t> | <t> | |||
Access to appropriate locking state will generally need no actions | Access to appropriate locking state will generally need no actions | |||
beyond | beyond access to the session. However, the SEQ4_STATUS bits need to be | |||
access to the session. However, the SEQ4_STATUS bits need to be | ||||
checked for lost locking state, including the need to reclaim | checked for lost locking state, including the need to reclaim | |||
locks after a server reboot, since there is always a possibility | locks after a server reboot, since there is always a possibility | |||
of locking state being lost. | of locking state being lost. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section title="Server Responsibilities Upon Migration" | <section anchor="SEC11-trans-server" numbered="true" toc="default"> | |||
anchor="SEC11-trans-server"> | <name>Server Responsibilities Upon Migration</name> | |||
<t> | <t> | |||
In the event of file system migration, when the client connects | In the event of file system migration, when the client connects | |||
to the destination server, that server needs to be able to provide the | to the destination server, that server needs to be able to provide the | |||
client continued to access | client continued access to the files it had open on the source server. | |||
the files it had open on the source server. There are two ways | There are two ways to provide this: | |||
to provide this: | </t> | |||
<list style="symbols"> | <ul spacing="normal"> | |||
<t> | <li> | |||
By provision of an fs-specific grace period, allowing the client the | By provision of an fs-specific grace period, allowing the client the | |||
ability to reclaim its locks, in a fashion similar to what would | ability to reclaim its locks, in a fashion similar to what would | |||
have been done in the | have been done in the case of recovery from a server restart. See | |||
case of recovery from a server restart. See | <xref target="SEC11-XS-reclaim" format="default"/> for a more complete | |||
<xref target="SEC11-XS-reclaim"/> for a more complete | ||||
discussion. | discussion. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
By implementing Transparent State Migration possibly in | By implementing Transparent State Migration possibly in | |||
connection with session migration, the server can provide | connection with session migration, the server can provide | |||
the client immediate access to the state built up on the | the client immediate access to the state built up on the | |||
source server, on the destination. | source server on the destination server. | |||
<vspace blankLines="1"/> | </t> | |||
<t> | ||||
These features are discussed separately in Sections | These features are discussed separately in Sections | |||
<xref target="SEC11-XS-lock" format="counter"/> and | <xref target="SEC11-XS-lock" format="counter"/> and | |||
<xref target="SEC11-XS-session" format="counter"/>, | <xref target="SEC11-XS-session" format="counter"/>, | |||
which discuss Transparent State Migration and session | which discuss Transparent State Migration and session | |||
migration respectively. | migration, respectively. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ul> | |||
<t> | <t> | |||
All the features described above can involve transfer of | All the features described above can involve transfer of | |||
lock-related information between source and destination | lock-related information between source and destination | |||
servers. In some cases, this transfer is a necessary part | servers. In some cases, this transfer is a necessary part | |||
of the implementation while in other cases it is a helpful | of the implementation, while in other cases, it is a helpful | |||
implementation aid which servers might or might not use. | implementation aid, which servers might or might not use. | |||
The sub-sections below discuss the information which would be | The subsections below discuss the information that would be | |||
transferred but do not define the specifics of the transfer | transferred but do not define the specifics of the transfer | |||
protocol. This is left as an implementation choice although | protocol. This is left as an implementation choice, although | |||
standards in this area could be developed at a later time. | standards in this area could be developed at a later time. | |||
</t> | </t> | |||
<section title="Server Responsibilities in Effecting State Reclaim after Mig | <section anchor="SEC11-XS-reclaim" numbered="true" toc="default"> | |||
ration" | <name>Server Responsibilities in Effecting State Reclaim after Migrati | |||
anchor="SEC11-XS-reclaim"> | on</name> | |||
<t> | <t> | |||
In this case, the destination server needs no knowledge of | In this case, the destination server needs no knowledge of | |||
the locks held | the locks held | |||
on the source server. It relies on the clients to accurately report | on the source server. It relies on the clients to accurately report | |||
(via reclaim operations) the locks previously held, and does not allow | (via reclaim operations) the locks previously held, and does not allow | |||
new locks to be granted on migrated file systems until the grace | new locks to be granted on migrated file systems until the grace | |||
period expires. Disallowing of new locks applies to | period expires. Disallowing of new locks applies to | |||
all clients accessing these file system, while grace period | all clients accessing these file systems, while grace period | |||
expiration occurs for each migrated client independently. | expiration occurs for each migrated client independently. | |||
</t> | </t> | |||
<t> | <t> | |||
During this grace period clients have the opportunity to use | During this grace period, clients have the opportunity to use | |||
reclaim operations to obtain locks for file system objects within | reclaim operations to obtain locks for file system objects within | |||
the migrated file system, in the same way that they do when | the migrated file system, in the same way that they do when | |||
recovering from server restart, and the servers typically | recovering from server restart, and the servers typically | |||
rely on clients to accurately report their locks, although they | rely on clients to accurately report their locks, although they | |||
have the option of subjecting these requests to verification. | have the option of subjecting these requests to verification. | |||
If the clients only reclaim locks held on the source server, no | If the clients only reclaim locks held on the source server, no | |||
conflict can arise. Once the client has reclaimed its locks, | conflict can arise. Once the client has reclaimed its locks, | |||
it indicates the completion of lock reclamation by performing a | it indicates the completion of lock reclamation by performing a | |||
RECLAIM_COMPLETE specifying rca_one_fs as TRUE. | RECLAIM_COMPLETE specifying rca_one_fs as TRUE. | |||
</t> | ||||
</t> | <t> | |||
<t> | ||||
While it is not necessary for source and destination servers | While it is not necessary for source and destination servers | |||
to co-operate to transfer information about locks, implementations | to cooperate to transfer information about locks, implementations | |||
are well-advised to consider transferring the following | are well advised to consider transferring the following | |||
useful information: | useful information: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If information about the set of clients that have | If information about the set of clients that have | |||
locking state for the transferred file system is made available, | locking state for the transferred file system is made available, | |||
the destination | the destination | |||
server will be able to terminate the grace period once all | server will be able to terminate the grace period once all | |||
such clients have reclaimed their locks, allowing normal | such clients have reclaimed their locks, allowing normal | |||
locking activity to resume earlier than it would have otherwise. | locking activity to resume earlier than it would have otherwise. | |||
</t> | </li> | |||
<t> | <li> | |||
Locking summary information for individual clients (at various | Locking summary information for individual clients (at various | |||
possible levels of detail) can detect | possible levels of detail) can detect | |||
some instances in which clients do not accurately represent the | some instances in which clients do not accurately represent the | |||
locks held on the source server. | locks held on the source server. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section anchor="SEC11-XS-lock" numbered="true" toc="default"> | |||
<section title="Server Responsibilities in Effecting Transparent State Migra | <name>Server Responsibilities in Effecting Transparent State Migration | |||
tion" | </name> | |||
anchor="SEC11-XS-lock"> | <t> | |||
<t> | ||||
The basic responsibility of the source server in effecting | The basic responsibility of the source server in effecting | |||
Transparent State Migration is to make available to the | Transparent State Migration is to make available to the | |||
destination server a description of each piece of locking state | destination server a description of each piece of locking state | |||
associated with the file system being migrated. In addition to | associated with the file system being migrated. In addition to | |||
client id string and verifier, the source server needs to provide, | client id string and verifier, the source server needs to provide | |||
for each stateid: | for each stateid: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The stateid including the current sequence value. | The stateid including the current sequence value. | |||
</t> | </li> | |||
<t> | <li> | |||
The associated client ID. | The associated client ID. | |||
</t> | </li> | |||
<t> | <li> | |||
The handle of the associated file. | The handle of the associated file. | |||
</t> | </li> | |||
<t> | <li> | |||
The type of the lock, such as open, byte-range lock, delegation, | The type of the lock, such as open, byte-range lock, delegation, | |||
or layout. | or layout. | |||
</t> | </li> | |||
<t> | <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. | |||
</t> | </li> | |||
<t> | <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. | |||
</t> | </li> | |||
<t> | <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 | |||
</t> | a byte-range. | |||
</list> | </li> | |||
</t> | </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"/>. | as described in <xref target="SECCON" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
A further server responsibility concerns locks that are revoked | A further server responsibility concerns locks that are revoked | |||
or otherwise lost during the process of file system migration. | or otherwise lost during the process of file system migration. | |||
Because locks that appear to be lost during the process of | Because locks that appear to be lost during the process of | |||
migration will be reclaimed by the client, the servers have to | migration will be reclaimed by the client, the servers have to | |||
take steps to ensure that locks revoked soon before or soon | take steps to ensure that locks revoked soon before or soon | |||
after migration are not inadvertently allowed to be reclaimed | after migration are not inadvertently allowed to be reclaimed | |||
in situations in which the continuity of lock possession | in situations in which the continuity of lock possession | |||
cannot be assured. | cannot be assured. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
For locks lost on the source but whose loss has not yet been | For locks lost on the source but whose loss has not yet been | |||
acknowledged by the client (by using FREE_STATEID), the | acknowledged by the client (by using FREE_STATEID), the | |||
destination must be aware of this loss so that it can deny | destination must be aware of this loss so that it can deny | |||
a request to reclaim them. | a request to reclaim them. | |||
</t> | </li> | |||
<t> | <li> | |||
For locks lost on the destination after the state transfer | For locks lost on the destination after the state transfer | |||
but before the client's RECLAIM_COMPLTE is done, the | but before the client's RECLAIM_COMPLETE is done, the | |||
destination server should note these and not allow them to | destination server should note these and not allow them to | |||
be reclaimed. | be reclaimed. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
An additional responsibility of the cooperating | An additional responsibility of the cooperating | |||
servers concerns situations | servers concerns situations | |||
in which a stateid cannot be transferred transparently because it | in which a stateid cannot be transferred transparently because it | |||
conflicts with an existing stateid held by the client and | conflicts with an existing stateid held by the client and | |||
associated with a different file system. In this case there | associated with a different file system. In this case, there | |||
are two valid choices: | are two valid choices: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Treat the transfer, as in NFSv4.0, as one without Transparent | Treat the transfer, as in NFSv4.0, as one without Transparent | |||
State Migration. In this case, conflicting locks cannot be | State Migration. In this case, conflicting locks cannot be | |||
granted until the client does a RECLAIM_COMPLETE, after | granted until the client does a RECLAIM_COMPLETE, after | |||
reclaiming the locks it had, with the exception of reclaims | reclaiming the locks it had, with the exception of reclaims | |||
denied because they were attempts to reclaim locks that had | denied because they were attempts to reclaim locks that had | |||
been lost. | been lost. | |||
</t> | </li> | |||
<t> | <li> | |||
Implement Transparent State Migration, except for the lock | Implement Transparent State Migration, except for the lock | |||
with the conflicting stateid. In this case, the client will | with the conflicting stateid. In this case, the client will | |||
be aware of a lost lock (through the SEQ4_STATUS flags) and be | be aware of a lost lock (through the SEQ4_STATUS flags) and be | |||
allowed to reclaim it. | allowed to reclaim it. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
When transferring state between the source and destination, the | When transferring state between the source and destination, the | |||
issues discussed in Section 7.2 of <xref target="RFC7931"/> | issues discussed in <xref target="RFC7931" sectionFormat="of" section="7 | |||
must still be attended to. In this case, | .2"/> | |||
the use of NFS4ERR_DELAY may still | must still be attended to. In this case, the use of NFS4ERR_DELAY may s | |||
till be | ||||
necessary in NFSv4.1, as it was in NFSv4.0, to prevent locking | necessary in NFSv4.1, as it was in NFSv4.0, to prevent locking | |||
state changing while it is being transferred. See | state changing while it is being transferred. See | |||
<xref target="err_DELAY"/> for information about | <xref target="err_DELAY" format="default"/> for information about | |||
appropriate client retry approaches in the event that NFS4ERR_DELAY | appropriate client retry approaches in the event that NFS4ERR_DELAY | |||
is returned. | is returned. | |||
</t> | </t> | |||
<t> | <t> | |||
There are a number of important differences in the NFS4.1 | There are a number of important differences in the NFS4.1 | |||
context: | context: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The absence of RELEASE_LOCKOWNER means that the one case | The absence of RELEASE_LOCKOWNER means that the one case | |||
in which an operation could not be deferred by use of | in which an operation could not be deferred by use of | |||
NFS4ERR_DELAY no longer exists. | NFS4ERR_DELAY no longer exists. | |||
</t> | </li> | |||
<t> | <li> | |||
Sequencing of operations is no longer done using owner-based | Sequencing of operations is no longer done using owner-based | |||
operation sequences numbers. Instead, sequencing is session- | operation sequences numbers. Instead, sequencing is session- | |||
based | based. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
As a result, when sessions are not transferred, the techniques | As a result, when sessions are not transferred, the techniques | |||
discussed in Section 7.2 of <xref target="RFC7931"/> | discussed in <xref target="RFC7931" sectionFormat="of" section="7.2"/> | |||
are adequate and will not | are adequate and will not be further discussed. | |||
be further discussed. | </t> | |||
</t> | </section> | |||
</section> | <section anchor="SEC11-XS-session" numbered="true" toc="default"> | |||
<section title="Server Responsibilities in Effecting Session Transfer" | <name>Server Responsibilities in Effecting Session Transfer</name> | |||
anchor="SEC11-XS-session"> | <t> | |||
<t> | ||||
The basic responsibility of the source server in effecting | The basic responsibility of the source server in effecting | |||
session transfer is to make available to the | session transfer is to make available to the | |||
destination server a description of the current state of each | destination server a description of the current state of each | |||
slot with the session, including: | slot with the session, including the following: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The last sequence value received for that slot. | The last sequence value received for that slot. | |||
</t> | </li> | |||
<t> | <li> | |||
Whether there is cached reply data for the last request | Whether there is cached reply data for the last request | |||
executed and, if so, the cached reply. | executed and, if so, the cached reply. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
</t> | ||||
<t> | ||||
When sessions are transferred, there are a number of issues that | When sessions are transferred, there are a number of issues that | |||
pose challenges in terms of making the transferred state | pose challenges in terms of making the transferred state | |||
unmodifiable during the period it is gathered up and | unmodifiable during the period it is gathered up and | |||
transferred to the destination server. | transferred to the destination server: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
A single session may be used to access multiple file systems, | A single session may be used to access multiple file systems, | |||
not all of which are being transferred. | not all of which are being transferred. | |||
</t> | </li> | |||
<t> | <li> | |||
Requests made on a session may, even if rejected, affect | Requests made on a session may, even if rejected, affect | |||
the state of the session by advancing the sequence number | the state of the session by advancing the sequence number | |||
associated with the slot used. | associated with the slot used. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
As a result, when the file system state might otherwise be | As a result, when the file system state might otherwise be | |||
considered unmodifiable, the client might have any number of | considered unmodifiable, the client might have any number of | |||
in-flight requests, each of which is capable of changing session | in-flight requests, each of which is capable of changing session | |||
state, which may be of a number of types: | state, which may be of a number of types: | |||
<list style ='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
Those requests that were processed on the migrating file system, | <li> | |||
Those requests that were processed on the migrating file system | ||||
before migration began. | before migration began. | |||
</t> | </li> | |||
<t> | <li> | |||
Those requests which got the error NFS4ERR_DELAY because the | Those requests that received the error NFS4ERR_DELAY because the | |||
file system being accessed was in the process of being | file system being accessed was in the process of being | |||
migrated. | migrated. | |||
</t> | </li> | |||
<t> | <li> | |||
Those requests which got the error NFS4ERR_MOVED because the | Those requests that received the error NFS4ERR_MOVED because the | |||
file system being accessed had been migrated. | file system being accessed had been migrated. | |||
</t> | </li> | |||
<t> | <li> | |||
Those requests that accessed the migrating file system, | Those requests that accessed the migrating file system | |||
in order to obtain location or status information. | in order to obtain location or status information. | |||
</t> | </li> | |||
<t> | <li> | |||
Those requests that did not reference the migrating file system. | Those requests that did not reference the migrating file system. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | <t> | |||
<t> | It should be noted that the history of any particular slot is likely | |||
It should be noted that the history of any | ||||
particular slot is likely | ||||
to include a number of these request classes. In the case in which | to include a number of these request classes. In the case in which | |||
a session which is migrated is used by file systems other than the | a session that is migrated is used by file systems other than the | |||
one migrated, requests of class 5 may be common and be the last | one migrated, requests of class 5 may be common and may be the last | |||
request processed, for many slots. | request processed for many slots. | |||
</t> | </t> | |||
<t> | <t> | |||
Since session state can change even after the locking | Since session state can change even after the locking | |||
state has been fixed as part of the migration process, | state has been fixed as part of the migration process, | |||
the session state known to the client could | the session state known to the client could be different from that on | |||
be different from that on | ||||
the destination server, which necessarily reflects the session | the destination server, which necessarily reflects the session | |||
state on the source server, at an earlier time. | state on the source server at an earlier time. | |||
In deciding how to deal with this situation, it is helpful to | In deciding how to deal with this situation, it is helpful to | |||
distinguish between two sorts of behavioral consequences of | distinguish between two sorts of behavioral consequences of | |||
the choice of initial sequence ID values. | the choice of initial sequence ID values: | |||
<list style ='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
The error NFS4ERR_SEQ_MISORDERED is returned when the sequence ID | The error NFS4ERR_SEQ_MISORDERED is returned when the sequence ID | |||
in a request is neither equal to the last one seen for the | in a request is neither equal to the last one seen for the | |||
current slot nor the next greater one. | current slot nor the next greater one. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
In view of the difficulty of arriving at a mutually acceptable | In view of the difficulty of arriving at a mutually acceptable | |||
value for the correct last sequence value | value for the correct last sequence value at the point of migration, | |||
at the point of migration, | ||||
it may be necessary for the server to show some degree of | it may be necessary for the server to show some degree of | |||
forbearance, when the sequence ID is one that would be | forbearance when the sequence ID is one that would be | |||
considered unacceptable if session migration were not | considered unacceptable if session migration were not | |||
involved. | involved. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
Returning the cached reply for a previously executed | Returning the cached reply for a previously executed | |||
request when the sequence ID | request when the sequence ID | |||
in the request matches the last value recorded for the slot. | in the request matches the last value recorded for the slot. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
In the cases in which an error is returned and there is no | In the cases in which an error is returned and there is no | |||
possibility of any non-idempotent operation having been executed, | possibility of any non-idempotent operation having been executed, | |||
it may not be necessary to adhere to this as strictly as might | it may not be necessary to adhere to this as strictly as might | |||
be proper if session migration were not | be proper if session migration were not involved. For example, | |||
involved. For example, the fact that the error NFS4ERR_DELAY | the fact that the error NFS4ERR_DELAY | |||
was returned may not assist the client in any material way, while | was returned may not assist the client in any material way, while | |||
the fact that NFS4ERR_MOVED was returned by the source server | the fact that NFS4ERR_MOVED was returned by the source server | |||
may not be relevant when the request was reissued, directed | may not be relevant when the request was reissued and directed | |||
to the | to the destination server. | |||
destination server. | </t> | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
An important issue is that the specification needs to take note of | An important issue is that the specification needs to take note of | |||
all potential COMPOUNDs, even if they might be unlikely | all potential COMPOUNDs, even if they might be unlikely | |||
in practice. For example, a COMPOUND is allowed to access | in practice. For example, a COMPOUND is allowed to access | |||
multiple file systems and might perform non-idempotent operations | multiple file systems and might perform non-idempotent operations | |||
in some of them before accessing a file system being migrated. | in some of them before accessing a file system being migrated. | |||
Also, a COMPOUND may return considerable data in the response, | Also, a COMPOUND may return considerable data in the response | |||
before | before being rejected with NFS4ERR_DELAY or NFS4ERR_MOVED, and may | |||
being rejected with NFS4ERR_DELAY or NFS4ERR_MOVED, and may | ||||
in addition be marked as sa_cachethis. However, note that | in addition be marked as sa_cachethis. However, note that | |||
if the client and server adhere to rules in | if the client and server adhere to rules in | |||
<xref target="err_DELAY"/>, there is no possibility of | <xref target="err_DELAY" format="default"/>, there is no possibility of | |||
non-idempotent operations being spuriously reissued after receiving | non-idempotent operations being spuriously reissued after receiving | |||
NFS4ERR_DELAY response. | NFS4ERR_DELAY response. | |||
</t> | </t> | |||
<t> | <t> | |||
To address these issues, a destination server MAY do any of | To address these issues, a destination server <bcp14>MAY</bcp14> do any | |||
the following when implementing session transfer. | of | |||
<list style ='symbols'> | the following when implementing session transfer: | |||
<t> | </t> | |||
<ul spacing="normal"> | ||||
<li> | ||||
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. | |||
</t> | </li> | |||
<t> | <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. | |||
</t> | </li> | |||
<t> | <li> | |||
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, | particular slot on the destination server, avoid reporting | |||
avoid reporting NFS4ERR_SEQ_MISORDERED or | NFS4ERR_SEQ_MISORDERED or returning a cached reply that contains | |||
returning a cached reply returning NFS4ERR_DELAY or NFS4ERR_MOVED, | either NFS4ERR_DELAY or NFS4ERR_MOVED and consists solely of | |||
where the reply consists solely of a series of operations | a series of operations where the response is NFS4_OK until the | |||
where the response is NFS4_OK until the final error. | final error. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <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"/>, 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: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Not responding with NFS4ERR_SEQ_MISORDERED for the initial | Not responding with NFS4ERR_SEQ_MISORDERED for the initial | |||
request on a slot within a transferred session, since the | request on a slot within a transferred session because the | |||
destination server cannot be aware of requests made by the | destination server cannot be aware of requests made by the | |||
client after the server handoff but before the client became | client after the server handoff but before the client became | |||
aware of the shift. In cases in which NFS4ERR_SEQ_MISORDERED | aware of the shift. In cases in which NFS4ERR_SEQ_MISORDERED | |||
would normally have been reported, the request is to be processed | would normally have been reported, the request is to be processed | |||
normally, as a new request. | normally as a new request. | |||
</t> | </li> | |||
<t> | <li> | |||
Replying as it would for a retry whenever the sequence matches | Replying as it would for a retry whenever the sequence matches | |||
that transferred by the source server, even though this would | that transferred by the source server, even though this would | |||
not provide retry handling for requests issued after the server | not provide retry handling for requests issued after the server | |||
handoff, under the assumption that when such requests are issued | handoff, under the assumption that, when such requests are issued, | |||
they will never be responded to in a state-changing fashion, | they will never be responded to in a state-changing fashion, | |||
making retry support for them unnecessary. | making retry support for them unnecessary. | |||
</t> | </li> | |||
<t> | <li> | |||
Once a non-retry SEQUENCE is received for a given slot, using | Once a non-retry SEQUENCE is received for a given slot, using | |||
that as the basis for further sequence checking, with no further | that as the basis for further sequence checking, with no further | |||
reference to the sequence value transferred by the source. | reference to the sequence value transferred by the source server. | |||
server. | </li> | |||
</t> | </ul> | |||
</list> | </section> | |||
</t> | </section> | |||
<section anchor="effecting_referrals" numbered="true" toc="default"> | ||||
</section> | <name>Effecting File System Referrals</name> | |||
</section> | <t> | |||
<section anchor="effecting_referrals" | ||||
title="Effecting File System Referrals"> | ||||
<t> | ||||
Referrals are effected when an absent file system is encountered | Referrals are effected when an absent file system is encountered | |||
and one or more alternate locations are made available by the | and one or more alternate locations are made available by the | |||
fs_locations or fs_locations_info attributes. The client will | fs_locations or fs_locations_info attributes. The client will | |||
typically get an NFS4ERR_MOVED error, fetch the appropriate | typically get an NFS4ERR_MOVED error, fetch the appropriate | |||
location information, and proceed to access the file system on | location information, and proceed to access the file system on | |||
a different server, even though it retains its logical position | a different server, even though it retains its logical position | |||
within the original namespace. Referrals differ from migration | within the original namespace. Referrals differ from migration | |||
events in that they happen only when the client has not | events in that they happen only when the client has not | |||
previously referenced the file system in question (so there | previously referenced the file system in question (so there | |||
is nothing to transition). Referrals can only come into | is nothing to transition). Referrals can only come into | |||
effect when an absent file system is encountered at its | effect when an absent file system is encountered at its | |||
root. | root. | |||
</t> | </t> | |||
<t> | <t> | |||
The examples given in the sections below are somewhat artificial in | The examples given in the sections below are somewhat artificial in | |||
that an actual client will not typically do a multi-component | that an actual client will not typically do a multi-component | |||
look up, but will have cached information regarding the upper levels | look up, but will have cached information regarding the upper levels | |||
of the name hierarchy. However, these examples are chosen to make | of the name hierarchy. However, these examples are chosen to make | |||
the required behavior clear and easy to put within the scope of a | the required behavior clear and easy to put within the scope of a | |||
small number of requests, without getting a discussion of the details of | small number of requests, without getting into a discussion of the details of | |||
how specific clients might choose to cache things. | how specific clients might choose to cache things. | |||
</t> | </t> | |||
<section anchor="referrals_lookup" | <section anchor="referrals_lookup" numbered="true" toc="default"> | |||
title="Referral Example (LOOKUP)"> | <name>Referral Example (LOOKUP)</name> | |||
<t> | <t> | |||
Let us suppose that the following COMPOUND is sent in an | Let us suppose that the following COMPOUND is sent in an | |||
environment in which /this/is/the/path is absent from the | environment in which /this/is/the/path is absent from the | |||
target server. This may be for a number of reasons. It may | target server. This may be for a number of reasons. It may | |||
be that the file system has moved, or it may be that | be that the file system has moved, or it may be that | |||
the target server is functioning mainly, or solely, to refer | the target server is functioning mainly, or solely, to refer | |||
clients to the servers on which various file systems are located. | clients to the servers on which various file systems are located. | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
PUTROOTFH | PUTROOTFH | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "this" | LOOKUP "this" | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "is" | LOOKUP "is" | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "the" | LOOKUP "the" | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "path" | LOOKUP "path" | |||
</t> | </li> | |||
<t> | <li> | |||
GETFH | GETFH | |||
</t> | </li> | |||
<t> | <li> | |||
GETATTR (fsid, fileid, size, time_modify) | GETATTR (fsid, fileid, size, time_modify) | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Under the given circumstances, the following will be the result. | Under the given circumstances, the following will be the result. | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | PUTROOTFH --> NFS_OK. The current fh is now the root of | |||
PUTROOTFH --> NFS_OK. The current fh is now the root of | ||||
the pseudo-fs. | the pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "this" --> NFS_OK. The current fh is for /this and is | LOOKUP "this" --> NFS_OK. The current fh is for /this and is | |||
within the pseudo-fs. | within the pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "is" --> NFS_OK. The current fh is for /this/is | LOOKUP "is" --> NFS_OK. The current fh is for /this/is | |||
and is within the pseudo-fs. | and is within the pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the | LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the | |||
and is within the pseudo-fs. | and is within the pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "path" --> NFS_OK. The current fh is for | LOOKUP "path" --> NFS_OK. The current fh is for | |||
/this/is/the/path and is within a new, absent file system, but ... | /this/is/the/path and is within a new, absent file system, but ... | |||
the client will never see the value of that fh. | the client will never see the value of that fh. | |||
</t> | </li> | |||
<t> | <li> | |||
GETFH --> NFS4ERR_MOVED. | GETFH --> NFS4ERR_MOVED. | |||
Fails because current fh is in an absent file system at the start of | Fails because current fh is in an absent file system at the start of | |||
the operation, and the specification makes no exception for GETFH. | the operation, and the specification makes no exception for GETFH. | |||
</t> | </li> | |||
<t> | <li> | |||
GETATTR (fsid, fileid, size, time_modify). | GETATTR (fsid, fileid, size, time_modify). | |||
Not executed because the failure of the GETFH stops processing | Not executed because the failure of the GETFH stops processing | |||
of the COMPOUND. | of the COMPOUND. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Given the failure of the GETFH, the client has the job of | Given the failure of the GETFH, the client has the job of | |||
determining the root of the absent file system and where to find | determining the root of the absent file system and where to find | |||
that file system, i.e., the server and path relative to that | that file system, i.e., the server and path relative to that | |||
server's root fh. Note that in this example, the client did | server's root fh. Note that in this example, the client did | |||
not obtain filehandles and attribute information (e.g., fsid) for | not obtain filehandles and attribute information (e.g., fsid) for | |||
the intermediate directories, so that it would not be sure where | the intermediate directories, so that it would not be sure where | |||
the absent file system starts. It could be the case, for example, | the absent file system starts. It could be the case, for example, | |||
that /this/is/the is the root of the moved file system and that | that /this/is/the is the root of the moved file system and that | |||
the reason that the look up of "path" succeeded is that the | the reason that the look up of "path" succeeded is that the | |||
file system was not absent on that operation but was moved between the l ast | file system was not absent on that operation but was moved between the l ast | |||
LOOKUP and the GETFH (since COMPOUND is not atomic). Even if we | LOOKUP and the GETFH (since COMPOUND is not atomic). Even if we | |||
had the fsids for all of the intermediate directories, we could | had the fsids for all of the intermediate directories, we could | |||
have no way of knowing that /this/is/the/path was the root of a | have no way of knowing that /this/is/the/path was the root of a | |||
new file system, since we don't yet have its fsid. | new file system, since we don't yet have its fsid. | |||
</t> | </t> | |||
<t> | <t> | |||
In order to get the necessary information, let us re-send the | In order to get the necessary information, let us re-send the | |||
chain of LOOKUPs with GETFHs and GETATTRs to at least get the | chain of LOOKUPs with GETFHs and GETATTRs to at least get the | |||
fsids so we can be sure where the appropriate file system boundaries are . | fsids so we can be sure where the appropriate file system boundaries are . | |||
The client could choose to get fs_locations_info | The client could choose to get fs_locations_info | |||
at the same time but in | at the same time but in | |||
most cases the client will have a good guess as to where file system | most cases the client will have a good guess as to where file system | |||
boundaries are (because of where NFS4ERR_MOVED was, and was not, | boundaries are (because of where NFS4ERR_MOVED was, and was not, | |||
received) making fetching of fs_locations_info unnecessary. | received) making fetching of fs_locations_info unnecessary. | |||
</t> | </t> | |||
<t> | <dl newline="false" spacing="normal"> | |||
<list style='hanging'> | <dt>OP01:</dt> | |||
<t hangText='OP01:'> | <dd><t>PUTROOTFH --> NFS_OK</t> | |||
PUTROOTFH --> NFS_OK | <ul><li>Current fh is root of pseudo-fs.</li></ul> | |||
</t> | </dd> | |||
<t hangText='- '> | <dt>OP02:</dt> | |||
Current fh is root of pseudo-fs. | <dd><t>GETATTR(fsid) --> NFS_OK</t> | |||
</t> | <ul><li>Just for completeness. Normally, clients will know the fsid | |||
<t hangText='OP02:'> | ||||
GETATTR(fsid) --> NFS_OK | ||||
</t> | ||||
<t hangText='- '> | ||||
Just for completeness. Normally, clients will know the fsid | ||||
of the pseudo-fs as soon as they establish communication with | of the pseudo-fs as soon as they establish communication with | |||
a server. | a server.</li></ul> | |||
</t> | </dd> | |||
<t hangText='OP03:'> | <dt>OP03:</dt> | |||
LOOKUP "this" --> NFS_OK | <dd>LOOKUP "this" --> NFS_OK</dd> | |||
</t> | <dt>OP04:</dt> | |||
<t hangText='OP04:'> | <dd><t>GETATTR(fsid) --> NFS_OK</t> | |||
GETATTR(fsid) --> NFS_OK | <ul><li> | |||
</t> | Get current fsid to see where file system boundaries are. The fsid | |||
<t hangText='- '> | ||||
Get current fsid to see where file system boundaries are. The fsid | ||||
will be that for the pseudo-fs in this example, so no | will be that for the pseudo-fs in this example, so no | |||
boundary. | boundary.</li></ul> | |||
</t> | </dd> | |||
<t hangText='OP05:'> | <dt>OP05:</dt> | |||
GETFH --> NFS_OK | <dd><t>GETFH --> NFS_OK</t> | |||
</t> | <ul><li>Current fh is for /this and is within pseudo-fs.</li></ul> | |||
<t hangText='- '> | </dd> | |||
Current fh is for /this and is within pseudo-fs. | <dt>OP06:</dt> | |||
</t> | <dd><t>LOOKUP "is" --> NFS_OK</t> | |||
<t hangText='OP06:'> | <ul><li>Current fh is for /this/is and is within pseudo-fs.</li></ul> | |||
LOOKUP "is" --> NFS_OK | </dd> | |||
</t> | <dt>OP07:</dt> | |||
<t hangText='- '> | <dd><t>GETATTR(fsid) --> NFS_OK</t> | |||
Current fh is for /this/is and is within pseudo-fs. | <ul><li> | |||
</t> | ||||
<t hangText='OP07:'> | ||||
GETATTR(fsid) --> NFS_OK | ||||
</t> | ||||
<t hangText='- '> | ||||
Get current fsid to see where file system boundaries are. The fsid | Get current fsid to see where file system boundaries are. The fsid | |||
will be that for the pseudo-fs in this example, so no | will be that for the pseudo-fs in this example, so no | |||
boundary. | boundary.</li></ul> | |||
</t> | </dd> | |||
<t hangText='OP08:'> | <dt>OP08:</dt> | |||
GETFH --> NFS_OK | <dd> | |||
</t> | <t>GETFH --> NFS_OK</t> | |||
<t hangText='- '> | <ul><li>Current fh is for /this/is and is within pseudo-fs.</li></ul> | |||
Current fh is for /this/is and is within pseudo-fs. | </dd> | |||
</t> | <dt>OP09:</dt> | |||
<t hangText='OP09:'> | <dd> | |||
LOOKUP "the" --> NFS_OK | <t>LOOKUP "the" --> NFS_OK</t> | |||
</t> | <ul><li> | |||
<t hangText='- '> | Current fh is for /this/is/the and is within pseudo-fs.</li></ul> | |||
Current fh is for /this/is/the and is within pseudo-fs. | </dd> | |||
</t> | <dt>OP10:</dt> | |||
<t hangText='OP10:'> | <dd> | |||
GETATTR(fsid) --> NFS_OK | <t>GETATTR(fsid) --> NFS_OK</t> | |||
</t> | <ul><li> | |||
<t hangText='- '> | Get current fsid to see where file system boundaries are. The fsid | |||
Get current fsid to see where file system boundaries are. The fsid | ||||
will be that for the pseudo-fs in this example, so no | will be that for the pseudo-fs in this example, so no | |||
boundary. | boundary.</li></ul> | |||
</t> | </dd> | |||
<t hangText='OP11:'> | <dt>OP11:</dt> | |||
GETFH --> NFS_OK | <dd> | |||
</t> | <t>GETFH --> NFS_OK</t> | |||
<t hangText='- '> | <ul><li>Current fh is for /this/is/the and is within pseudo-fs.</li></ | |||
Current fh is for /this/is/the and is within pseudo-fs. | ul> | |||
</t> | </dd> | |||
<t hangText='OP12:'> | <dt>OP12:</dt> | |||
LOOKUP "path" --> NFS_OK | <dd> | |||
</t> | <t>LOOKUP "path" --> NFS_OK</t> | |||
<t hangText='- '> | <ul><li> | |||
Current fh is for /this/is/the/path and is within a new, | Current fh is for /this/is/the/path and is within a new, | |||
absent file system, but ... | absent file system, but ...</li> | |||
</t> | <li> | |||
<t hangText='- '> | The client will never see the value of that fh.</li></ul> | |||
The client will never see the value of that fh. | </dd> | |||
</t> | <dt>OP13:</dt> | |||
<t hangText='OP13:'> | <dd> | |||
GETATTR(fsid, fs_locations_info) --> NFS_OK | <t>GETATTR(fsid, fs_locations_info) --> NFS_OK</t> | |||
</t> | <ul><li> | |||
<t hangText='- '> | ||||
We are getting the fsid to know where the file system boundaries are. | We are getting the fsid to know where the file system boundaries are. | |||
In this operation, the fsid will be different than that of the | In this operation, the fsid will be different than that of the | |||
parent directory (which in turn was retrieved in OP10). | parent directory (which in turn was retrieved in OP10). | |||
Note that the fsid we are given will not necessarily be preserved at t he new | Note that the fsid we are given will not necessarily be preserved at t he new | |||
location. That fsid might be different, and in fact the fsid | location. That fsid might be different, and in fact the fsid | |||
we have for this file system might be a valid fsid of a different | we have for this file system might be a valid fsid of a different | |||
file system on that new server. | file system on that new server.</li> | |||
</t> | <li> | |||
<t hangText='- '> | ||||
In this particular case, we are pretty sure anyway that what | In this particular case, we are pretty sure anyway that what | |||
has moved is /this/is/the/path rather than /this/is/the | has moved is /this/is/the/path rather than /this/is/the | |||
since we have the fsid of the latter and it is that of the | since we have the fsid of the latter and it is that of the | |||
pseudo-fs, which presumably cannot move. However, in other | pseudo-fs, which presumably cannot move. However, in other | |||
examples, we might not have this kind of information to rely | examples, we might not have this kind of information to rely | |||
on (e.g., /this/is/the might be a non-pseudo file system | on (e.g., /this/is/the might be a non-pseudo file system | |||
separate from /this/is/the/path), so we need to have | separate from /this/is/the/path), so we need to have | |||
other reliable source information on the boundary of the file system | other reliable source information on the boundary of the file system | |||
that is moved. If, for example, the file system /this/is | that is moved. If, for example, the file system /this/is | |||
had moved, we would have a case of migration rather than | had moved, we would have a case of migration rather than | |||
referral, and once the boundaries of the migrated file system | referral, and once the boundaries of the migrated file system | |||
was clear we could fetch fs_locations_info. | was clear we could fetch fs_locations_info.</li> | |||
</t> | <li> | |||
<t hangText='- '> | ||||
We are fetching fs_locations_info because the fact that we got an | We are fetching fs_locations_info because the fact that we got an | |||
NFS4ERR_MOVED at this point means that it is most likely that | NFS4ERR_MOVED at this point means that it is most likely that | |||
this is a referral and we need the destination. Even if it is | this is a referral and we need the destination. Even if it is | |||
the case that /this/is/the is a file system that has | the case that /this/is/the is a file system that has | |||
migrated, we will still need the location information for that | migrated, we will still need the location information for that | |||
file system. | file system.</li></ul></dd> | |||
</t> | ||||
<t hangText='OP14:'> | <dt>OP14:</dt> | |||
GETFH --> NFS4ERR_MOVED | <dd> | |||
</t> | <t>GETFH --> NFS4ERR_MOVED</t> | |||
<t hangText='- '> | <ul><li> | |||
Fails because current fh is in an absent file system at the start of | Fails because current fh is in an absent file system at the start of | |||
the operation, and the specification makes no exception for GETFH. No te | the operation, and the specification makes no exception for GETFH. No te | |||
that this means the server will never send the client a | that this means the server will never send the client a | |||
filehandle from within an absent file system. | filehandle from within an absent file system.</li></ul> | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | <t> | |||
<t> | ||||
Given the above, the client knows where the root of the absent file | Given the above, the client knows where the root of the absent file | |||
system is (/this/is/the/path) by noting where the change of | system is (/this/is/the/path) by noting where the change of | |||
fsid occurred (between "the" and "path"). The | fsid occurred (between "the" and "path"). The | |||
fs_locations_info attribute also gives the client the | fs_locations_info attribute also gives the client the | |||
actual location of | actual location of | |||
the absent file system, so that the referral can proceed. The | the absent file system, so that the referral can proceed. The | |||
server gives the client the bare minimum of information about the | server gives the client the bare minimum of information about the | |||
absent file system so that there will be very little scope for | absent file system so that there will be very little scope for | |||
problems of conflict between information sent by the referring | problems of conflict between information sent by the referring | |||
server and information of the file system's home. No filehandles | server and information of the file system's home. No filehandles | |||
and very few attributes are present on the referring server, and the | and very few attributes are present on the referring server, and the | |||
client can treat those it receives as transient | client can treat those it receives as transient | |||
information with the function of enabling the referral. | information with the function of enabling the referral. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="referrals_readdir" | <section anchor="referrals_readdir" numbered="true" toc="default"> | |||
title="Referral Example (READDIR)"> | <name>Referral Example (READDIR)</name> | |||
<t> | <t> | |||
Another context in which a client may encounter referrals is when | Another context in which a client may encounter referrals is when | |||
it does a READDIR on a directory in which some of the sub-directories | it does a READDIR on a directory in which some of the sub-directories | |||
are the roots of absent file systems. | are the roots of absent file systems. | |||
</t> | </t> | |||
<t> | <t> | |||
Suppose such a directory is read as follows: | Suppose such a directory is read as follows: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
PUTROOTFH | PUTROOTFH | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "this" | LOOKUP "this" | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "is" | LOOKUP "is" | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "the" | LOOKUP "the" | |||
</t> | </li> | |||
<t> | <li> | |||
READDIR (fsid, size, time_modify, mounted_on_fileid) | READDIR (fsid, size, time_modify, mounted_on_fileid) | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
In this case, because rdattr_error is not requested, | In this case, because rdattr_error is not requested, | |||
fs_locations_info | fs_locations_info | |||
is not requested, and some of the attributes cannot be provided, the | is not requested, and some of the attributes cannot be provided, the | |||
result will be an NFS4ERR_MOVED error on the READDIR, with the | result will be an NFS4ERR_MOVED error on the READDIR, with the | |||
detailed results as follows: | detailed results as follows: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | PUTROOTFH --> NFS_OK. The current fh is at the root of the | |||
PUTROOTFH --> NFS_OK. The current fh is at the root of the | ||||
pseudo-fs. | pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "this" --> NFS_OK. The current fh is for /this and is | LOOKUP "this" --> NFS_OK. The current fh is for /this and is | |||
within the pseudo-fs. | within the pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "is" --> NFS_OK. The current fh is for /this/is | LOOKUP "is" --> NFS_OK. The current fh is for /this/is | |||
and is within the pseudo-fs. | and is within the pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the | LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the | |||
and is within the pseudo-fs. | and is within the pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
READDIR (fsid, size, time_modify, mounted_on_fileid) --> | READDIR (fsid, size, time_modify, mounted_on_fileid) --> | |||
NFS4ERR_MOVED. Note that the same error would have been | NFS4ERR_MOVED. Note that the same error would have been | |||
returned if /this/is/the had migrated, but it is returned because the | returned if /this/is/the had migrated, but it is returned because the | |||
directory contains the root of an absent file system. | directory contains the root of an absent file system. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
So now suppose that we re-send with rdattr_error: | So now suppose that we re-send with rdattr_error: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
PUTROOTFH | PUTROOTFH | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "this" | LOOKUP "this" | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "is" | LOOKUP "is" | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "the" | LOOKUP "the" | |||
</t> | </li> | |||
<t> | <li> | |||
READDIR (rdattr_error, fsid, size, time_modify, mounted_on_fileid) | READDIR (rdattr_error, fsid, size, time_modify, mounted_on_fileid) | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The results will be: | The results will be: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | PUTROOTFH --> NFS_OK. The current fh is at the root of the | |||
PUTROOTFH --> NFS_OK. The current fh is at the root of the | ||||
pseudo-fs. | pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "this" --> NFS_OK. The current fh is for /this and is | LOOKUP "this" --> NFS_OK. The current fh is for /this and is | |||
within the pseudo-fs. | within the pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "is" --> NFS_OK. The current fh is for /this/is | LOOKUP "is" --> NFS_OK. The current fh is for /this/is | |||
and is within the pseudo-fs. | and is within the pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the | LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the | |||
and is within the pseudo-fs. | and is within the pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
READDIR (rdattr_error, fsid, size, time_modify, mounted_on_fileid) | READDIR (rdattr_error, fsid, size, time_modify, mounted_on_fileid) | |||
--> NFS_OK. The attributes for directory entry with the | --> NFS_OK. The attributes for directory entry with the | |||
component named "path" will only contain | component named "path" will only contain | |||
rdattr_error | rdattr_error | |||
with the value NFS4ERR_MOVED, together with an fsid | with the value NFS4ERR_MOVED, together with an fsid | |||
value and a value for mounted_on_fileid. | value and a value for mounted_on_fileid. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Suppose we do another READDIR to get fs_locations_info (although | Suppose we do another READDIR to get fs_locations_info (although | |||
we could have used a GETATTR directly, as in | we could have used a GETATTR directly, as in | |||
<xref target="referrals_lookup" />). | <xref target="referrals_lookup" format="default"/>). | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
PUTROOTFH | PUTROOTFH | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "this" | LOOKUP "this" | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "is" | LOOKUP "is" | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "the" | LOOKUP "the" | |||
</t> | </li> | |||
<t> | <li> | |||
READDIR (rdattr_error, fs_locations_info, mounted_on_fileid, fsid, | READDIR (rdattr_error, fs_locations_info, mounted_on_fileid, fsid, | |||
size, time_modify) | size, time_modify) | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The results would be: | The results would be: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | PUTROOTFH --> NFS_OK. The current fh is at the root of the | |||
PUTROOTFH --> NFS_OK. The current fh is at the root of the | ||||
pseudo-fs. | pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "this" --> NFS_OK. The current fh is for /this and is | LOOKUP "this" --> NFS_OK. The current fh is for /this and is | |||
within the pseudo-fs. | within the pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "is" --> NFS_OK. The current fh is for /this/is | LOOKUP "is" --> NFS_OK. The current fh is for /this/is | |||
and is within the pseudo-fs. | and is within the pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the | LOOKUP "the" --> NFS_OK. The current fh is for /this/is/the | |||
and is within the pseudo-fs. | and is within the pseudo-fs. | |||
</t> | </li> | |||
<t> | <li> | |||
READDIR (rdattr_error, fs_locations_info, mounted_on_fileid, fsid, | READDIR (rdattr_error, fs_locations_info, mounted_on_fileid, fsid, | |||
size, time_modify) --> NFS_OK. The attributes will be as shown below. | size, time_modify) --> NFS_OK. The attributes will be as shown bel | |||
</t> | ow. | |||
</list> | </li> | |||
</t> | </ul> | |||
<t> | <t> | |||
The attributes for the directory entry with the | The attributes for the directory entry with the | |||
component named "path" will only contain: | component named "path" will only contain: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
rdattr_error (value: NFS_OK) | rdattr_error (value: NFS_OK) | |||
</t> | </li> | |||
<t> | <li> | |||
fs_locations_info | fs_locations_info | |||
</t> | </li> | |||
<t> | <li> | |||
mounted_on_fileid (value: unique fileid within referring file system) | mounted_on_fileid (value: unique fileid within referring file system) | |||
</t> | </li> | |||
<t> | <li> | |||
fsid (value: unique value within referring server) | fsid (value: unique value within referring server) | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The attributes for entry "path" will not contain size or | The attributes for entry "path" will not contain size or | |||
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" | <section anchor="fs_locations" numbered="true" toc="default"> | |||
title="The Attribute fs_locations"> | <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> | |||
<t> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
struct fs_location4 { | struct fs_location4 { | |||
utf8str_cis server<>; | utf8str_cis server<>; | |||
pathname4 rootpath; | pathname4 rootpath; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <sourcecode type="xdr"><![CDATA[ | |||
</t> | ||||
<t> | ||||
<figure> | ||||
<artwork> | ||||
struct fs_locations4 { | struct fs_locations4 { | |||
pathname4 fs_root; | pathname4 fs_root; | |||
fs_location4 locations<>; | fs_location4 locations<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
</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 | |||
same path within their namespaces, an array of server names may | same path within their namespaces, an array of server names may | |||
be provided. An | be provided. An | |||
entry in the server array is a UTF-8 string and represents one | entry in the server array is a UTF-8 string and represents one | |||
of a | of a | |||
traditional DNS host name, IPv4 address, IPv6 address, or a | traditional DNS host name, IPv4 address, IPv6 address, or a | |||
zero-length string. | zero-length string. | |||
An IPv4 or IPv6 address is represented as a universal | An IPv4 or IPv6 address is represented as a universal | |||
address (see <xref target="netaddr4"/> and <xref | address (see <xref target="netaddr4" format="default"/> and <xref target=" | |||
target="RFC5665"/>), minus the netid, and either with | RFC5665" format="default"/>), minus the netid, and either with | |||
or without the trailing ".p1.p2" suffix that | or without the trailing ".p1.p2" suffix that | |||
represents the port number. If the suffix is omitted, | represents the port number. If the suffix is omitted, | |||
then the default port, 2049, SHOULD be assumed. | then the default port, 2049, <bcp14>SHOULD</bcp14> be assumed. | |||
A zero-length string SHOULD be used to indicate the current address | A zero-length string <bcp14>SHOULD</bcp14> be used to indicate the current address | |||
being used for the RPC call. It is not | being used for the RPC call. It is not | |||
a requirement that all servers that share the same rootpath | a requirement that all servers that share the same rootpath | |||
be listed | be listed | |||
in one fs_location4 instance. The array of server names is provided for | in one fs_location4 instance. The array of server names is provided for | |||
convenience. Servers that share the same rootpath may also be listed | convenience. Servers that share the same rootpath may also be listed | |||
in separate fs_location4 entries in the fs_locations attribute. | in separate fs_location4 entries in the fs_locations attribute. | |||
</t> | </t> | |||
<t> | <t> | |||
The fs_locations4 data type and the fs_locations attribute each | The fs_locations4 data type and the fs_locations attribute each | |||
contain an array of | contain an array of | |||
such locations. Since the namespace of each server may be | such locations. Since the namespace of each server may be | |||
constructed differently, the "fs_root" field is provided. The | constructed differently, the "fs_root" field is provided. The | |||
path represented | path represented | |||
by fs_root represents the location of the file system in the | by fs_root represents the location of the file system in the | |||
current server's namespace, i.e., that of the | current server's namespace, i.e., that of the | |||
server from which the fs_locations attribute was obtained. The | server from which the fs_locations attribute was obtained. The | |||
fs_root path is meant to aid the client by clearly referencing | fs_root path is meant to aid the client by clearly referencing | |||
the root of the file system whose locations are being reported, | the root of the file system whose locations are being reported, | |||
no matter what object within the current file system the | no matter what object within the current file system the | |||
current filehandle designates. The fs_root is simply the | current filehandle designates. The fs_root is simply the | |||
pathname the client used to reach the object on the current server | pathname the client used to reach the object on the current server | |||
(i.e., the object to which the fs_locations attribute applies). | (i.e., the object to which the fs_locations attribute applies). | |||
</t> | </t> | |||
<t> | <t> | |||
When the fs_locations attribute | When the fs_locations attribute | |||
is interrogated and there are no alternate file system locations, | is interrogated and there are no alternate file system locations, | |||
the server SHOULD return a zero-length array of fs_location4 | the server <bcp14>SHOULD</bcp14> return a zero-length array of fs_location4 | |||
structures, together with a valid fs_root. | structures, together with a valid fs_root. | |||
</t> | </t> | |||
<t> | <t> | |||
As an example, suppose there is a replicated file system located | As an example, suppose there is a replicated file system located | |||
at two | at two | |||
servers (servA and servB). At servA, the file system is located at | servers (servA and servB). At servA, the file system is located at | |||
path /a/b/c. At, servB the file system is located at path /x/y/z. | path /a/b/c. At, servB the file system is located at path /x/y/z. | |||
If the client were to obtain the fs_locations value for the | If the client were to obtain the fs_locations value for the | |||
directory at /a/b/c/d, it might not necessarily know | directory at /a/b/c/d, it might not necessarily know | |||
that the file system's root is located in servA's namespace | that the file system's root is located in servA's namespace | |||
at /a/b/c. When the client switches to servB, it will need | at /a/b/c. When the client switches to servB, it will need | |||
to determine that the directory it first referenced at servA is now | to determine that the directory it first referenced at servA is now | |||
represented by the path /x/y/z/d on servB. To facilitate this, the | represented by the path /x/y/z/d on servB. To facilitate this, the | |||
fs_locations attribute provided by servA would have an fs_root value | fs_locations attribute provided by servA would have an fs_root value | |||
of /a/b/c and two entries in fs_locations. One entry in fs_locations | of /a/b/c and two entries in fs_locations. One entry in fs_locations | |||
will be for itself (servA) and the other will be for servB with a | will be for itself (servA) and the other will be for servB with a | |||
path of /x/y/z. With this information, the client is able to | path of /x/y/z. With this information, the client is able to | |||
substitute /x/y/z for the /a/b/c at the beginning of its access | substitute /x/y/z for the /a/b/c at the beginning of its access | |||
path and construct /x/y/z/d to use for the new server. | path and construct /x/y/z/d to use for the new server. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that there is no requirement that the number | Note that there is no requirement that the number | |||
of components in each rootpath be the same; there | of components in each rootpath be the same; there | |||
is no relation between the number of components in | is no relation between the number of components in | |||
rootpath or fs_root, and none of the components | rootpath or fs_root, and none of the components | |||
in a rootpath and fs_root have to be the same. In | in a rootpath and fs_root have to be the same. In | |||
the above example, we could have had a third element | the above example, we could have had a third element | |||
in the locations array, with server equal to "servC" | in the locations array, with server equal to "servC" | |||
and rootpath equal to "/I/II", and a fourth element in | and rootpath equal to "/I/II", and a fourth element in | |||
locations with server equal to "servD" and rootpath | locations with server equal to "servD" and rootpath | |||
equal to "/aleph/beth/gimel/daleth/he". | equal to "/aleph/beth/gimel/daleth/he". | |||
</t> | </t> | |||
<t> | <t> | |||
The relationship between fs_root to a rootpath is | The relationship between fs_root to a rootpath is | |||
that the client replaces the pathname indicated in | that the client replaces the pathname indicated in | |||
fs_root for the current server for the substitute | fs_root for the current server for the substitute | |||
indicated in rootpath for the new server. | indicated in rootpath for the new server. | |||
</t> | </t> | |||
<t> | <t> | |||
For an example of a referred or migrated file | For an example of a referred or migrated file | |||
system, suppose there is a file system located | system, suppose there is a file system located | |||
at serv1. At serv1, the file system is located at | at serv1. At serv1, the file system is located at | |||
/az/buky/vedi/glagoli. The client finds that object | /az/buky/vedi/glagoli. The client finds that object | |||
at glagoli has migrated (or is a referral). The | at glagoli has migrated (or is a referral). The | |||
client gets the fs_locations attribute, which contains | client gets the fs_locations attribute, which contains | |||
an fs_root of /az/buky/vedi/glagoli, and one element | an fs_root of /az/buky/vedi/glagoli, and one element | |||
in the locations array, with server equal to serv2, | in the locations array, with server equal to serv2, | |||
and rootpath equal to /izhitsa/fita. The client | and rootpath equal to /izhitsa/fita. The client | |||
replaces /az/buky/vedi/glagoli with /izhitsa/fita, | replaces /az/buky/vedi/glagoli with /izhitsa/fita, | |||
and uses the latter pathname on serv2. | and uses the latter pathname on serv2. | |||
</t> | </t> | |||
<t> | ||||
<t> | Thus, the server <bcp14>MUST</bcp14> return an fs_root that is equal | |||
Thus, the server MUST return an fs_root that is equal | ||||
to the path the client used to reach the object to which the | to the path the client used to reach the object to which the | |||
fs_locations attribute applies. Otherwise, the | fs_locations attribute applies. Otherwise, the | |||
client cannot determine the new path to use on the new server. | client cannot determine the new path to use on the new server. | |||
</t> | </t> | |||
<t> | <t> | |||
Since the fs_locations attribute lacks information defining various | Since the fs_locations attribute lacks information defining various | |||
attributes of the various file system choices presented, it SHOULD | attributes of the various file system choices presented, it <bcp14>SHOULD</ bcp14> | |||
only be interrogated and used when fs_locations_info is not available. | only be interrogated and used when fs_locations_info is not available. | |||
When fs_locations is used, information about the | When fs_locations is used, information about the | |||
specific locations should be assumed based on the following rules. | specific locations should be assumed based on the following rules. | |||
</t> | </t> | |||
<t> | <t> | |||
The following rules are general and apply irrespective of the | The following rules are general and apply irrespective of the | |||
context. | context. | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
All listed | All listed | |||
file system instances should be considered as of the | file system instances should be considered as of the | |||
same handle class, if and only if, the | same handle class, if and only if, the | |||
current fh_expire_type attribute does not include the | current fh_expire_type attribute does not include the | |||
FH4_VOL_MIGRATION | FH4_VOL_MIGRATION | |||
bit. Note that in the case of referral, filehandle issues do | bit. Note that in the case of referral, filehandle issues do | |||
not apply since there can be no filehandles known within the | not apply since there can be no filehandles known within the | |||
current file system, nor is there any access to the fh_expire_type | current file system, nor is there any access to the fh_expire_type | |||
attribute on the referring (absent) file system. | attribute on the referring (absent) file system. | |||
</t> | </li> | |||
<t> | <li> | |||
All listed file system instances should be considered as of the | All listed file system instances should be considered as of the | |||
same fileid class if and only if the | same fileid class if and only if the | |||
fh_expire_type attribute indicates persistent filehandles and | fh_expire_type attribute indicates persistent filehandles and | |||
does not include the FH4_VOL_MIGRATION | does not include the FH4_VOL_MIGRATION | |||
bit. Note that in the case of referral, fileid issues do | bit. Note that in the case of referral, fileid issues do | |||
not apply since there can be no fileids known within the | not apply since there can be no fileids known within the | |||
referring (absent) file system, nor is there any access to | referring (absent) file system, nor is there any access to | |||
the fh_expire_type attribute. | the fh_expire_type attribute. | |||
</t> | </li> | |||
<t> | <li> | |||
All file system instances | All file system instances | |||
servers should be considered as of different | servers should be considered as of different | |||
change classes. | change classes. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
For other class assignments, handling of file system | For other class assignments, handling of file system | |||
transitions depends on the reasons for the transition: | transitions depends on the reasons for the transition: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
When the transition is due to migration, that is, the client was | When the transition is due to migration, that is, the client was | |||
directed to a new file system after receiving an NFS4ERR_MOVED error, | directed to a new file system after receiving an NFS4ERR_MOVED error, | |||
the target should be | the target should be | |||
treated as being of the same | treated as being of the same | |||
write-verifier class as the source. | write-verifier class as the source. | |||
</t> | </li> | |||
<t> | <li> | |||
When the transition is due to failover to another replica, | When the transition is due to failover to another replica, | |||
that is, the client selected another replica without | that is, the client selected another replica without | |||
receiving an NFS4ERR_MOVED error, the target should be | receiving an NFS4ERR_MOVED error, the target should be | |||
treated as being of a different | treated as being of a different | |||
write-verifier class from the source. | write-verifier class from the source. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The specific choices reflect typical implementation patterns for | The specific choices reflect typical implementation patterns for | |||
failover and controlled migration, respectively. Since other | failover and controlled migration, respectively. Since other | |||
choices are possible and useful, this information is better | choices are possible and useful, this information is better | |||
obtained by using fs_locations_info. When a server implementation | obtained by using fs_locations_info. When a server implementation | |||
needs to communicate other choices, it MUST support the | needs to communicate other choices, it <bcp14>MUST</bcp14> support the | |||
fs_locations_info attribute. | fs_locations_info attribute. | |||
</t> | </t> | |||
<t> | <t> | |||
See <xref target="SECCON" /> for a | See <xref target="SECCON" format="default"/> for a | |||
discussion on the recommendations for the security | discussion on the recommendations for the security | |||
flavor to be used by any GETATTR operation that | flavor to be used by any GETATTR operation that | |||
requests the "fs_locations" attribute. | requests the fs_locations attribute. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="The Attribute fs_locations_info" | <section anchor="SEC11-li-new" numbered="true" toc="default"> | |||
anchor="SEC11-li-new"> | <name>The Attribute fs_locations_info</name> | |||
<t> | <t> | |||
The fs_locations_info attribute is intended as a more functional | The fs_locations_info attribute is intended as a more functional | |||
replacement for the fs_locations attribute which will continue to exist | replacement for the fs_locations attribute, which will continue to exist | |||
and be | and be supported. Clients can use it to get a more complete set of | |||
supported. Clients can use it to get a more complete set of | ||||
data about alternative file system locations, including additional | data about alternative file system locations, including additional | |||
network paths to access replicas in use and additional replicas. | network paths to access replicas in use and additional replicas. | |||
When the server does not support | When the server does not support | |||
fs_locations_info, fs_locations can be used to get a subset of the | fs_locations_info, fs_locations can be used to get a subset of the | |||
data. A server that supports fs_locations_info MUST support | data. A server that supports fs_locations_info <bcp14>MUST</bcp14> suppor t | |||
fs_locations as well. | fs_locations as well. | |||
</t> | </t> | |||
<t> | <t> | |||
There is additional data present in | There is additional data present in | |||
fs_locations_info, that is not available in fs_locations: | fs_locations_info that is not available in fs_locations: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
Attribute continuity information. This information | Attribute continuity information. This information | |||
will allow a client to select a | will allow a client to select a | |||
replica that meets the transparency requirements of the | replica that meets the transparency requirements of the | |||
applications accessing the data and to leverage | applications accessing the data and to leverage | |||
optimizations due to the server guarantees of attribute | optimizations due to the server guarantees of attribute | |||
continuity (e.g., if the | continuity (e.g., if the | |||
change attribute of a file of the file system is continuous | change attribute of a file of the file system is continuous | |||
between multiple replicas, | between multiple replicas, | |||
the client does not have to invalidate the file's cache | the client does not have to invalidate the file's cache | |||
when switching to a different replica). | when switching to a different replica). | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
File system identity information that indicates when multiple | File system identity information that indicates when multiple | |||
replicas, from the client's point of view, correspond to the | replicas, from the client's point of view, correspond to the | |||
same target file system, allowing them to be used | same target file system, allowing them to be used | |||
interchangeably, without disruption, as distinct synchronized | interchangeably, without disruption, as distinct synchronized | |||
replicas of the same file data. | replicas of the same file data. | |||
<vspace blankLines="1"/> | </t> | |||
<t> | ||||
Note that having two replicas with common identity information is | Note that having two replicas with common identity information is | |||
distinct from the case of two (trunked) paths to the same | distinct from the case of two (trunked) paths to the same | |||
replica. | replica. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
Information that will bear on the suitability of various | Information that will bear on the suitability of various | |||
replicas, depending on the use that the client intends. For | replicas, depending on the use that the client intends. For | |||
example, many applications need an absolutely up-to-date copy | example, many applications need an absolutely up-to-date copy | |||
(e.g., those that write), while others may only need access to | (e.g., those that write), while others may only need access to | |||
the most up-to-date copy reasonably available. | the most up-to-date copy reasonably available. | |||
</t> | </li> | |||
<t> | <li> | |||
Server-derived preference information for replicas, which can | Server-derived preference information for replicas, which can | |||
be used to implement load-balancing while giving the client | be used to implement load-balancing while giving the client | |||
the entire file system list to be used in case the primary fails. | the entire file system list to be used in case the primary fails. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The fs_locations_info attribute is structured similarly to the | The fs_locations_info attribute is structured similarly to the | |||
fs_locations attribute. A top-level structure | fs_locations attribute. A top-level structure | |||
(fs_locations_info4) contains the entire attribute including the root | (fs_locations_info4) contains the entire attribute including the root | |||
pathname of the file system and an array of lower-level structures that | pathname of the file system and an array of lower-level structures that | |||
define replicas that share a common rootpath on their respective | define replicas that share a common rootpath on their respective | |||
servers. The lower-level structure in turn | servers. The lower-level structure in turn | |||
(fs_locations_item4) contains a specific pathname and information on one | (fs_locations_item4) contains a specific pathname and information on one | |||
or more individual network access paths. For that last lowest level, | or more individual network access paths. For that last, lowest level, | |||
fs_locations_info has an fs_locations_server4 | fs_locations_info has an fs_locations_server4 | |||
structure that contains per-server-replica information in addition | structure that contains per-server-replica information in addition | |||
to the file system | to the file system | |||
location entry. This per-server-replica information includes a | location entry. This per-server-replica information includes a | |||
nominally opaque array, fls_info, within which specific pieces | nominally opaque array, fls_info, within which specific pieces | |||
of information | of information are located at the specific indices listed below. | |||
are located at the specific indices listed below. | </t> | |||
</t> | <t> | |||
<t> | ||||
Two fs_location_server4 entries that are within different | Two fs_location_server4 entries that are within different | |||
fs_location_item4 structures are never trunkable, while two entries | fs_location_item4 structures are never trunkable, while two entries | |||
within in the same fs_location_item4 structure might or might not be | within in the same fs_location_item4 structure might or might not be | |||
trunkable. Two entries that are trunkable will have identical | trunkable. Two entries that are trunkable will have identical | |||
identity information, although, as noted above, the converse is | identity information, although, as noted above, the converse is | |||
not the case. | not the case. | |||
</t> | </t> | |||
<t> | <t> | |||
The attribute will always contain at least a single fs_locations_server | The attribute will always contain at least a single fs_locations_server | |||
entry. Typically, there will be an entry with the FS4LIGF_CUR_REQ | entry. Typically, there will be an entry with the FS4LIGF_CUR_REQ | |||
flag set, although in the case of a referral there will be no | flag set, although in the case of a referral there will be no | |||
entry with that flag set. | entry with that flag set. | |||
</t> | </t> | |||
<t> | <t> | |||
It should be noted that fs_locations_info attributes returned by | It should be noted that fs_locations_info attributes returned by | |||
servers for various replicas may differ for various reasons. | servers for various replicas may differ for various reasons. | |||
One server may know about a set of replicas that are not known to | One server may know about a set of replicas that are not known to | |||
other servers. Further, compatibility attributes may differ. | other servers. Further, compatibility attributes may differ. | |||
Filehandles might be of the same class going from replica A to | Filehandles might be of the same class going from replica A to | |||
replica B but not going in the reverse direction. This might happen | replica B but not going in the reverse direction. This might happen | |||
because the filehandles are the same, but | because the filehandles are the same, but | |||
replica B's server implementation might not have provision to note | replica B's server implementation might not have provision to note | |||
and report that equivalence. | and report that equivalence. | |||
</t> | </t> | |||
<t> | <t> | |||
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> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
/* | /* | |||
* 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; | |||
}; | }; | |||
/* | /* | |||
* Byte indices of items within | * Byte indices of items within | |||
* fls_info: flag fields, class numbers, | * fls_info: flag fields, class numbers, | |||
* bytes indicating ranks and orders. | * bytes indicating ranks and orders. | |||
*/ | */ | |||
const FSLI4BX_GFLAGS = 0; | const FSLI4BX_GFLAGS = 0; | |||
const FSLI4BX_TFLAGS = 1; | const FSLI4BX_TFLAGS = 1; | |||
skipping to change at line 18528 ¶ | skipping to change at line 18626 ¶ | |||
*/ | */ | |||
const FSLI4TF_RDMA = 0x01; | const FSLI4TF_RDMA = 0x01; | |||
/* | /* | |||
* Defines a set of replicas sharing | * Defines a set of replicas sharing | |||
* a common value of the rootpath | * a common value of the rootpath | |||
* within the corresponding | * within the corresponding | |||
* single-server namespaces. | * single-server namespaces. | |||
*/ | */ | |||
struct fs_locations_item4 { | struct fs_locations_item4 { | |||
fs_locations_server4 fli_entries<>; | fs_locations_server4 fli_entries<>; | |||
pathname4 fli_rootpath; | pathname4 fli_rootpath; | |||
}; | }; | |||
/* | /* | |||
* Defines the overall structure of | * Defines the overall structure of | |||
* the fs_locations_info attribute. | * the fs_locations_info attribute. | |||
*/ | */ | |||
struct fs_locations_info4 { | struct fs_locations_info4 { | |||
uint32_t fli_flags; | uint32_t fli_flags; | |||
int32_t fli_valid_for; | int32_t fli_valid_for; | |||
pathname4 fli_fs_root; | pathname4 fli_fs_root; | |||
fs_locations_item4 fli_items<>; | fs_locations_item4 fli_items<>; | |||
}; | }; | |||
/* | /* | |||
* Flag bits in fli_flags. | * Flag bits in fli_flags. | |||
*/ | */ | |||
const FSLI4IF_VAR_SUB = 0x00000001; | const FSLI4IF_VAR_SUB = 0x00000001; | |||
typedef fs_locations_info4 fattr4_fs_locations_info; | typedef fs_locations_info4 fattr4_fs_locations_info; | |||
]]></sourcecode> | ||||
</artwork> | <t> | |||
</figure> | ||||
<t> | ||||
As noted above, the fs_locations_info attribute, when supported, may | As noted above, the fs_locations_info attribute, when supported, may | |||
be requested of absent file systems without causing NFS4ERR_MOVED to | be requested of absent file systems without causing NFS4ERR_MOVED to | |||
be returned. It is generally expected that it will be available for | be returned. It is generally expected that it will be available for | |||
both present and absent file systems even if only a single | both present and absent file systems even if only a single | |||
fs_locations_server4 entry is present, designating the current (present) | fs_locations_server4 entry is present, designating the current (present) | |||
file system, or two fs_locations_server4 entries designating the | file system, or two fs_locations_server4 entries designating the | |||
previous location of an absent file system (the one just referenced) and i ts | previous location of an absent file system (the one just referenced) and i ts | |||
successor location. Servers are strongly urged to support this | successor location. Servers are strongly urged to support this | |||
attribute on all file systems if they support it on any file system. | attribute on all file systems if they support it on any file system. | |||
</t> | </t> | |||
<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" | <section anchor="SEC11-fsli-server" numbered="true" toc="default"> | |||
title="The fs_locations_server4 Structure"> | <name>The fs_locations_server4 Structure</name> | |||
<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 for the same replica, each | multiple fs_locations_server4 structures, each | |||
specifying a network path to the chosen replica. | specifying a network path to the chosen replica, for the same | |||
</t> | replica. | |||
<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 | |||
replication or referral. When there are more than two such entries, | replication or referral. When there are more than two such entries, | |||
majority voting can be used to exclude a single erroneous entry from | majority voting can be used to exclude a single erroneous entry from | |||
consideration. In the case in which trunking information is provided | consideration. In the case in which trunking information is provided | |||
for a replica currently being accessed, the additional trunked addresses | for a replica currently being accessed, the additional trunked addresses | |||
can be ignored while access continues on the address currently being | can be ignored while access continues on the address currently being | |||
used, even if the entry corresponding to that path might be considered | used, even if the entry corresponding to that path might be considered | |||
invalid. | invalid. | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
An indication of how up-to-date the file system is (fls_currency) in | An indication of how up-to-date the file system is (fls_currency) in | |||
seconds. This value | seconds. This value | |||
is relative to the master copy. A negative | is relative to the master copy. A negative | |||
value indicates that the server is unable to give any | value indicates that the server is unable to give any | |||
reasonably useful value here. A value of zero indicates that the | reasonably useful value here. A value of zero indicates that the | |||
file system is the actual writable data or a reliably coherent | file system is the actual writable data or a reliably coherent | |||
and fully up-to-date copy. Positive values indicate how | and fully up-to-date copy. Positive values indicate how | |||
out-of-date this copy can normally be before it is considered for | out-of-date this copy can normally be before it is considered for | |||
update. Such a value is not a guarantee that such updates | update. Such a value is not a guarantee that such updates | |||
will always be performed on the required schedule but instead | will always be performed on the required schedule but instead | |||
serves as a hint about how far the copy of the data would be | serves as a hint about how far the copy of the data would be | |||
expected to be behind the most up-to-date copy. | expected to be behind the most up-to-date copy. | |||
</t> | </li> | |||
<t> | <li> | |||
A counted array of one-byte values (fls_info) containing | A counted array of one-byte values (fls_info) containing | |||
information about the particular file system instance. This | information about the particular file system instance. This | |||
data includes general flags, transport capability flags, | data includes general flags, transport capability flags, | |||
file system equivalence class information, and selection | file system equivalence class information, and selection | |||
priority information. The encoding will be discussed below. | priority information. The encoding will be discussed below. | |||
</t> | </li> | |||
<t> | <li> | |||
The server string (fls_server). For the case of the | The server string (fls_server). For the case of the | |||
replica currently | replica currently | |||
being accessed (via GETATTR), a zero-length string MAY be used to | being accessed (via GETATTR), a zero-length string <bcp14>MAY</bcp14> be used to | |||
indicate the current address being used for the RPC call. | indicate the current address being used for the RPC call. | |||
The fls_server field can also be an IPv4 or IPv6 address, | The fls_server field can also be an IPv4 or IPv6 address, | |||
formatted the same way as an IPv4 or IPv6 address in the "server" | formatted the same way as an IPv4 or IPv6 address in the "server" | |||
field of the fs_location4 data type (see | field of the fs_location4 data type (see | |||
<xref target="fs_locations"/>). | <xref target="fs_locations" format="default"/>). | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
With the exception of the transport-flag field (at offset | With the exception of the transport-flag field (at offset | |||
FSLI4BX_TFLAGS with the fls_info array), all of this data defined | FSLI4BX_TFLAGS with the fls_info array), all of this data defined | |||
in this specification applies | in this specification applies to the replica specified by the entry, | |||
to the replica specified by the entry, rather that the specific | rather than the specific network path used to access it. | |||
network path used to access it. The classification of data in | The classification of data in extensions to this data is discussed below | |||
extensions to this data is discussed below. | . | |||
</t> | </t> | |||
<t> | <t> | |||
Data within the fls_info array is in the form of 8-bit data items | Data within the fls_info array is in the form of 8-bit data items | |||
with constants giving the offsets within the array of various | with constants giving the offsets within the array of various | |||
values describing this particular file system instance. | values describing this particular file system instance. | |||
This style of | This style of | |||
definition was chosen, in preference to explicit XDR | definition was chosen, in preference to explicit XDR | |||
structure definitions for these values, for a number of | structure definitions for these values, for a number of | |||
reasons. | reasons. | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
The kinds of data in the fls_info array, representing flags, | The kinds of data in the fls_info array, representing flags, | |||
file system classes, and priorities among sets of file systems | file system classes, and priorities among sets of file systems | |||
representing the same data, are such that 8 bits provide | representing the same data, are such that 8 bits provide | |||
a quite acceptable range of values. Even where there might | a quite acceptable range of values. Even where there might | |||
be more than 256 such file system instances, having more than | be more than 256 such file system instances, having more than | |||
256 distinct classes or priorities is unlikely. | 256 distinct classes or priorities is unlikely. | |||
</t> | </li> | |||
<t> | <li> | |||
Explicit definition of the various specific data items within | Explicit definition of the various specific data items within | |||
XDR would limit expandability in that any extension within | XDR would limit expandability in that any extension within | |||
would require yet another attribute, | would require yet another attribute, | |||
leading to specification and implementation clumsiness. | leading to specification and implementation clumsiness. | |||
In the context of the NFSv4 extension model in effect at the time | In the context of the NFSv4 extension model in effect at the time | |||
fs_locations_info was designed (i.e. that described in | fs_locations_info was designed (i.e., that which is described in | |||
RFC5661 <xref target="RFC5661"/>), this would necessitate a new minor | RFC 5661 <xref target="RFC5661" format="default"/>), this would | |||
version | necessitate a new minor version | |||
to effect any Standards Track extension to the data in in | to effect any Standards Track extension to the data in fls_info. | |||
fls_info. | </li> | |||
</t> | </ul> | |||
</list> | <t> | |||
</t> | ||||
<t> | ||||
The set of fls_info data is subject to expansion in a future minor | The set of fls_info data is subject to expansion in a future minor | |||
version, or in a Standards Track RFC, within the context of a single | version or in a Standards Track RFC within the context of a single | |||
minor version. The server SHOULD NOT send and the client MUST NOT | minor version. The server <bcp14>SHOULD NOT</bcp14> send and the | |||
use indices within the fls_info array or flag bits that are not | client <bcp14>MUST NOT</bcp14> use indices within the fls_info array | |||
defined in | or flag bits that are not defined in Standards Track RFCs. | |||
Standards Track RFCs. | </t> | |||
</t> | <t> | |||
<t> | In light of the new extension model defined in RFC 8178 | |||
In light of the new extension model defined in RFC8178 | <xref target="RFC8178" format="default"/> | |||
<xref target="RFC8178"/> | ||||
and the fact that the individual items within fls_info are not | and the fact that the individual items within fls_info are not | |||
explicitly referenced in the XDR, the following practices should be | explicitly referenced in the XDR, the following practices should be | |||
followed when extending or otherwise changing the structure of | followed when extending or otherwise changing the structure of | |||
the data returned in fls_info within the scope of a single minor | the data returned in fls_info within the scope of a single minor | |||
version. | version: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
All extensions need to be described by Standards Track documents. | All extensions need to be described by Standards Track documents. | |||
There | There is no need for such documents to be marked as updating | |||
is no need for such documents to be marked as updating | RFC 5661 <xref target="RFC5661" format="default"/> or this document. | |||
RFC5661 <xref target="RFC5661"/> or this document. | </li> | |||
</t> | <li> | |||
<t> | ||||
It needs to be made clear whether the information in any added data | It needs to be made clear whether the information in any added data | |||
items applies to the replica specified by the entry or to the specific | items applies to the replica specified by the entry or to the specific | |||
network paths specified in the entry. | network paths specified in the entry. | |||
</t> | </li> | |||
<t> | <li> | |||
There needs to be a reliable way defined to determine whether the | There needs to be a reliable way defined to determine whether the | |||
server is aware of the extension. This may be based on the | server is aware of the extension. This may be based on the | |||
length field of the fls_info array, but it is more flexible to | length field of the fls_info array, but it is more flexible to | |||
provide fs-scope or server-scope attributes to indicate what | provide fs-scope or server-scope attributes to indicate what | |||
extensions are provided. | extensions are provided. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
This encoding scheme can be adapted to the specification of | This encoding scheme can be adapted to the specification of | |||
multi-byte numeric values, even though none are currently | multi-byte numeric values, even though none are currently | |||
defined. If extensions are made via Standards Track RFCs, | defined. If extensions are made via Standards Track RFCs, | |||
multi-byte quantities will be encoded as a range of bytes | multi-byte quantities will be encoded as a range of bytes | |||
with a range of indices, with the byte interpreted in big-endian | with a range of indices, with the byte interpreted in big-endian | |||
byte order. Further, any such index assignments will be constrained | byte order. Further, any such index assignments will be constrained | |||
by the need for the relevant quantities not to | by the need for the relevant quantities not to | |||
cross XDR word boundaries. | cross XDR word boundaries. | |||
</t> | </t> | |||
<t> | <t> | |||
The fls_info array currently contains: | The fls_info array currently contains: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
Two 8-bit flag fields, one devoted to general file-system | Two 8-bit flag fields, one devoted to general file-system | |||
characteristics and a second reserved for transport-related | characteristics and a second reserved for transport-related | |||
capabilities. | capabilities. | |||
</t> | </li> | |||
<t> | <li> | |||
Six 8-bit class values that define various file system | Six 8-bit class values that define various file system | |||
equivalence classes as explained below. | equivalence classes as explained below. | |||
</t> | </li> | |||
<t> | <li> | |||
Four 8-bit priority values that govern file system selection | Four 8-bit priority values that govern file system selection | |||
as explained below. | as explained below. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The general file system characteristics flag (at byte index | The general file system characteristics flag (at byte index | |||
FSLI4BX_GFLAGS) has the following | FSLI4BX_GFLAGS) has the following | |||
bits defined within it: | bits defined within it: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
FSLI4GF_WRITABLE indicates that this file system target is writable, | FSLI4GF_WRITABLE indicates that this file system target is writable, | |||
allowing it to be selected by clients that may need to write | allowing it to be selected by clients that may need to write | |||
on this file system. When the current file system instance | on this file system. When the current file system instance | |||
is writable and is defined as of the same simultaneous use | is writable and is defined as of the same simultaneous use | |||
class (as specified by the value at index FSLI4BX_CLSIMUL) | class (as specified by the value at index FSLI4BX_CLSIMUL) | |||
to which the client was previously writing, then it must | to which the client was previously writing, then it must | |||
incorporate within its data any committed | incorporate within its data any committed | |||
write made on the source file system instance. See | write made on the source file system instance. See | |||
<xref target="SEC11-EFF-wv" />, which discusses | <xref target="SEC11-EFF-wv" format="default"/>, which discusses | |||
the write-verifier class. While there is no harm in not setting | the write-verifier class. While there is no harm in not setting | |||
this flag for a file system that turns out to be writable, | this flag for a file system that turns out to be writable, | |||
turning the flag on for a read-only file system can cause | turning the flag on for a read-only file system can cause | |||
problems for clients that select a migration or replication | problems for clients that select a migration or replication | |||
target based on the flag and then find themselves unable to write. | target based on the flag and then find themselves unable to write. | |||
</t> | </li> | |||
<t> | <li> | |||
FSLI4GF_CUR_REQ indicates that this replica is the one on which | FSLI4GF_CUR_REQ indicates that this replica is the one on which | |||
the request is being made. Only a single server entry may | the request is being made. Only a single server entry may | |||
have this flag set and, in the case of a referral, no entry | have this flag set and, in the case of a referral, no entry | |||
will have it set. Note that this flag might be set even if the | will have it set. Note that this flag might be set even if the | |||
request was made on a network access path different from any of | request was made on a network access path different from any of | |||
those specified in the current entry. | those specified in the current entry. | |||
</t> | </li> | |||
<t> | <li> | |||
FSLI4GF_ABSENT indicates that this entry corresponds to an absent | FSLI4GF_ABSENT indicates that this entry corresponds to an absent | |||
file system replica. It can only be set if FSLI4GF_CUR_REQ is set. | file system replica. It can only be set if FSLI4GF_CUR_REQ is set. | |||
When both such bits are set, it indicates that a file system | When both such bits are set, it indicates that a file system | |||
instance is not usable but that the information in the entry | instance is not usable but that the information in the entry | |||
can be used to determine the sorts of continuity available | can be used to determine the sorts of continuity available | |||
when switching from this replica to other possible replicas. | when switching from this replica to other possible replicas. | |||
Since this bit can only be true if FSLI4GF_CUR_REQ is true, the | Since this bit can only be true if FSLI4GF_CUR_REQ is true, the | |||
value could be determined using the fs_status attribute, but | value could be determined using the fs_status attribute, but | |||
the information is also made available here for the | the information is also made available here for the | |||
convenience of the client. An entry with this bit, since it | convenience of the client. An entry with this bit, since it | |||
represents a true file system (albeit absent), does not appear | represents a true file system (albeit absent), does not appear | |||
in the event of a referral, but only when a file system has | in the event of a referral, but only when a file system has | |||
been accessed at this location and has subsequently been migrated. | been accessed at this location and has subsequently been migrated. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
FSLI4GF_GOING indicates that a replica, while still available, | FSLI4GF_GOING indicates that a replica, while still available, | |||
should not be used further. The client, if using it, should | should not be used further. The client, if using it, should | |||
make an orderly transfer to another file system instance as | make an orderly transfer to another file system instance as | |||
expeditiously as possible. It is expected that file systems | expeditiously as possible. It is expected that file systems | |||
going out of service will be announced as FSLI4GF_GOING some time | going out of service will be announced as FSLI4GF_GOING some time | |||
before the actual loss of service. It is also expected that the | before the actual loss of service. It is also expected that the | |||
fli_valid_for value | fli_valid_for value | |||
will be sufficiently small to allow clients to detect and act | will be sufficiently small to allow clients to detect and act | |||
on scheduled events, while large enough that the cost of the | on scheduled events, while large enough that the cost of the | |||
requests to fetch the fs_locations_info values will not be | requests to fetch the fs_locations_info values will not be | |||
excessive. Values on the order of ten minutes seem | excessive. Values on the order of ten minutes seem | |||
reasonable. | reasonable. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
When this flag is seen as part of a transition into a new | When this flag is seen as part of a transition into a new | |||
file system, a client might choose to transfer immediately | file system, a client might choose to transfer immediately | |||
to another replica, or it may reference the current file system | to another replica, or it may reference the current file system | |||
and only transition when a migration event occurs. Similarly, | and only transition when a migration event occurs. Similarly, | |||
when this flag appears as a replica in the referral, clients | when this flag appears as a replica in the referral, clients | |||
would likely avoid being referred to this instance whenever | would likely avoid being referred to this instance whenever | |||
there is another choice. | there is another choice. | |||
<vspace blankLines='1' /> | </t> | |||
This flag, like the other items within fls_info applies to the | <t> | |||
replica, rather than to a particular path to that replica. When | This flag, like the other items within fls_info, applies to the | |||
it appears, a transition to a new replica rather than to a | replica rather than to a particular path to that replica. When | |||
it appears, a transition to a new replica, rather than to a | ||||
different path to the same replica, is indicated. | different path to the same replica, is indicated. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
FSLI4GF_SPLIT indicates that when a transition occurs from | FSLI4GF_SPLIT indicates that when a transition occurs from | |||
the current file system instance to this one, the replacement | the current file system instance to this one, the replacement | |||
may consist of multiple file systems. In this case, the | may consist of multiple file systems. In this case, the | |||
client has to be prepared for the possibility that objects | client has to be prepared for the possibility that objects | |||
on the same file system before migration will be on different ones | on the same file system before migration will be on different ones | |||
after. Note that FSLI4GF_SPLIT is not incompatible with the | after. Note that FSLI4GF_SPLIT is not incompatible with the | |||
file systems belonging to the same fileid | file systems belonging to the same fileid | |||
class | class | |||
since, if one has a set of fileids that are unique within | since, if one has a set of fileids that are unique within | |||
a file system, each subset assigned to a smaller file system after mig ration | a file system, each subset assigned to a smaller file system after mig ration | |||
would not have any conflicts internal to that file system. | would not have any conflicts internal to that file system. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
A client, in the case of a split file system, will interrogate | A client, in the case of a split file system, will interrogate | |||
existing files with which it has continuing connection (it | existing files with which it has continuing connection (it | |||
is free to simply forget cached filehandles). If the client | is free to simply forget cached filehandles). If the client | |||
remembers the directory filehandle associated with each open | remembers the directory filehandle associated with each open | |||
file, it may proceed upward using LOOKUPP to find the new file system | file, it may proceed upward using LOOKUPP to find the new file system | |||
boundaries. Note that in the event of a referral, there will | boundaries. Note that in the event of a referral, there will | |||
not be any such files and so these actions will not be performed. | not be any such files and so these actions will not be performed. | |||
Instead, a reference to a portion of the original | Instead, a reference to a portion of the original | |||
file system now split off into other file systems | file system now split off into other file systems | |||
will encounter an fsid change and possibly a | will encounter an fsid change and possibly a | |||
further referral. | further referral. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
Once the client recognizes that one file system has been split | Once the client recognizes that one file system has been split | |||
into two, it can prevent the disruption of running applications | into two, it can prevent the disruption of running applications | |||
by presenting the two file systems as a single | by presenting the two file systems as a single | |||
one until a convenient point to recognize the transition, | one until a convenient point to recognize the transition, | |||
such as a restart. This would require a mapping | such as a restart. This would require a mapping | |||
from the server's fsids to fsids as seen by the client, but | from the server's fsids to fsids as seen by the client, but | |||
this is already necessary for other reasons. As noted | this is already necessary for other reasons. As noted | |||
above, existing fileids within the two descendant file systems | above, existing fileids within the two descendant file systems | |||
will not conflict. Providing non-conflicting fileids for | will not conflict. Providing non-conflicting fileids for | |||
newly created files on the split file systems | newly created files on the split file systems | |||
is the responsibility of the server (or servers working in | is the responsibility of the server (or servers working in | |||
concert). The server can encode filehandles such | concert). The server can encode filehandles such | |||
that filehandles generated before the split event can be discerned | that filehandles generated before the split event can be discerned | |||
from those generated after the split, | from those generated after the split, | |||
allowing the server to determine when the need | allowing the server to determine when the need | |||
for emulating two file systems as one is over. | for emulating two file systems as one is over. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
Although it is possible for this flag to be present in the | Although it is possible for this flag to be present in the | |||
event of referral, it would generally be of little interest | event of referral, it would generally be of little interest | |||
to the client, since the client is not expected to have | to the client, since the client is not expected to have | |||
information regarding the current contents of the absent | information regarding the current contents of the absent | |||
file system. | file system. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ul> | |||
<t> | <t> | |||
The transport-flag field (at byte index FSLI4BX_TFLAGS) contains | The transport-flag field (at byte index FSLI4BX_TFLAGS) contains | |||
the following bits related to the transport | the following bits related to the transport | |||
capabilities of the specific network path(s) specified by the | capabilities of the specific network path(s) specified by the | |||
entry. | entry: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
FSLI4TF_RDMA indicates that any specified network paths | FSLI4TF_RDMA indicates that any specified network paths | |||
provide NFSv4.1 clients | provide NFSv4.1 clients | |||
access using an RDMA-capable transport. | access using an RDMA-capable transport. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Attribute continuity and file system identity information are | Attribute continuity and file system identity information are | |||
expressed by defining equivalence relations on the sets of | expressed by defining equivalence relations on the sets of | |||
file systems presented to the client. Each such relation | file systems presented to the client. Each such relation | |||
is expressed as a set of file system equivalence classes. | is expressed as a set of file system equivalence classes. | |||
For each relation, a file system has an 8-bit class number. | For each relation, a file system has an 8-bit class number. | |||
Two file systems belong to the same class if both have | Two file systems belong to the same class if both have | |||
identical non-zero class numbers. Zero is treated as | identical non-zero class numbers. Zero is treated as | |||
non-matching. Most often, | non-matching. Most often, | |||
the relevant question for the client will be whether a | the relevant question for the client will be whether a | |||
given replica is identical to / continuous with the current one in a | given replica is identical to / continuous with the current one in a | |||
given respect, but the information should be available also as to | given respect, but the information should be available also as to | |||
whether two other replicas match in that respect as well. | whether two other replicas match in that respect as well. | |||
</t> | </t> | |||
<t> | <t> | |||
The following fields specify the file system's class numbers | The following fields specify the file system's class numbers | |||
for the equivalence relations used in determining the nature of | for the equivalence relations used in determining the nature of | |||
file system transitions. See Sections | file system transitions. See Sections | |||
<xref target="SEC11-trans-oview" format="counter"/> | <xref target="SEC11-trans-oview" format="counter"/> | |||
through <xref target="SEC11-trans-server" format="counter"/> | through <xref target="SEC11-trans-server" format="counter"/> | |||
and their various subsections | and their various subsections | |||
for details about how | for details about how | |||
this information is to be used. Servers may assign these values | this information is to be used. Servers may assign these values | |||
as they wish, so long as file system instances that share the | as they wish, so long as file system instances that share the | |||
same value have the specified relationship to one another; | same value have the specified relationship to one another; | |||
conversely, file systems that have the specified relationship | conversely, file systems that have the specified relationship | |||
to one another share a common class value. As each instance | to one another share a common class value. As each instance | |||
entry is added, the relationships of this instance to previously | entry is added, the relationships of this instance to previously | |||
entered instances can be consulted, and if one is found that | entered instances can be consulted, and if one is found that | |||
bears the specified relationship, that entry's class value can | bears the specified relationship, that entry's class value can | |||
be copied to the new entry. When no such previous entry exists, | be copied to the new entry. When no such previous entry exists, | |||
a new value for that byte index (not previously used) can be | a new value for that byte index (not previously used) can be | |||
selected, most likely by incrementing the value of the last class | selected, most likely by incrementing the value of the last class | |||
value assigned for that index. | value assigned for that index. | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
The field with byte index FSLI4BX_CLSIMUL defines the | The field with byte index FSLI4BX_CLSIMUL defines the | |||
simultaneous-use class for the file system. | simultaneous-use class for the file system. | |||
</t> | </li> | |||
<t> | <li> | |||
The field with byte index FSLI4BX_CLHANDLE defines the handle | The field with byte index FSLI4BX_CLHANDLE defines the handle | |||
class for the file system. | class for the file system. | |||
</t> | </li> | |||
<t> | <li> | |||
The field with byte index FSLI4BX_CLFILEID defines the fileid | The field with byte index FSLI4BX_CLFILEID defines the fileid | |||
class for the file system. | class for the file system. | |||
</t> | </li> | |||
<t> | <li> | |||
The field with byte index FSLI4BX_CLWRITEVER defines the | The field with byte index FSLI4BX_CLWRITEVER defines the | |||
write-verifier class for the file system. | write-verifier class for the file system. | |||
</t> | </li> | |||
<t> | <li> | |||
The field with byte index FSLI4BX_CLCHANGE defines the change | The field with byte index FSLI4BX_CLCHANGE defines the change | |||
class for the file system. | class for the file system. | |||
</t> | </li> | |||
<t> | <li> | |||
The field with byte index FSLI4BX_CLREADDIR defines the readdir | The field with byte index FSLI4BX_CLREADDIR defines the readdir | |||
class for the file system. | class for the file system. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Server-specified preference information is also provided via | Server-specified preference information is also provided via | |||
8-bit values within the fls_info array. The values provide a | 8-bit values within the fls_info array. The values provide a | |||
rank and an order (see below) to be used with separate values | rank and an order (see below) to be used with separate values | |||
specifiable for the cases of read-only and writable file | specifiable for the cases of read-only and writable file | |||
systems. | systems. | |||
These values are compared | These values are compared | |||
for different file systems to establish the server-specified | for different file systems to establish the server-specified | |||
preference, with lower values indicating "more preferred". | preference, with lower values indicating "more preferred". | |||
</t> | </t> | |||
<t> | <t> | |||
Rank is used to express a strict server-imposed ordering on | Rank is used to express a strict server-imposed ordering on | |||
clients, with lower values indicating "more preferred". Clients | clients, with lower values indicating "more preferred". Clients | |||
should attempt to use all replicas with a given rank before they | should attempt to use all replicas with a given rank before they | |||
use one with a higher rank. Only if all of those file systems are | use one with a higher rank. Only if all of those file systems are | |||
unavailable should the client proceed to those of a higher rank. | unavailable should the client proceed to those of a higher rank. | |||
Because specifying a rank will override client preferences, servers | Because specifying a rank will override client preferences, servers | |||
should be conservative about using this mechanism, particularly | should be conservative about using this mechanism, particularly | |||
when the environment is one in which client communication characteristic s | when the environment is one in which client communication characteristic s | |||
are neither tightly controlled nor visible to the server. | are neither tightly controlled nor visible to the server. | |||
</t> | </t> | |||
<t> | <t> | |||
Within a rank, the order value is used to specify the server's | Within a rank, the order value is used to specify the server's | |||
preference to guide the client's selection when the client's own | preference to guide the client's selection when the client's own | |||
preferences are not controlling, with lower values of order | preferences are not controlling, with lower values of order | |||
indicating "more preferred". If replicas are approximately equal | indicating "more preferred". If replicas are approximately equal | |||
in all respects, clients should defer to the order specified by the | in all respects, clients should defer to the order specified by the | |||
server. When clients look at server latency as part of their | server. When clients look at server latency as part of their | |||
selection, they are free to use this criterion, but it is suggested | selection, they are free to use this criterion, but it is suggested | |||
that when latency differences are not significant, the | that when latency differences are not significant, the | |||
server-specified order should guide selection. | server-specified order should guide selection. | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
The field at byte index FSLI4BX_READRANK gives the rank value to | The field at byte index FSLI4BX_READRANK gives the rank value to | |||
be used for read-only access. | be used for read-only access. | |||
</t> | </li> | |||
<t> | <li> | |||
The field at byte index FSLI4BX_READORDER gives the order value to | The field at byte index FSLI4BX_READORDER gives the order value to | |||
be used for read-only access. | be used for read-only access. | |||
</t> | </li> | |||
<t> | <li> | |||
The field at byte index FSLI4BX_WRITERANK gives the rank value to | The field at byte index FSLI4BX_WRITERANK gives the rank value to | |||
be used for writable access. | be used for writable access. | |||
</t> | </li> | |||
<t> | <li> | |||
The field at byte index FSLI4BX_WRITEORDER gives the order value to | The field at byte index FSLI4BX_WRITEORDER gives the order value to | |||
be used for writable access. | be used for writable access. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Depending on the potential need for write access by a given client, | Depending on the potential need for write access by a given client, | |||
one of the pairs of rank and order values is used. | one of the pairs of rank and order values is used. | |||
The read rank and order should only be used | The read rank and order should only be used | |||
if the client knows that only reading will ever be done or if it is | if the client knows that only reading will ever be done or if it is | |||
prepared to switch to a different replica in the event that any | prepared to switch to a different replica in the event that any | |||
write access capability is required in the future. | write access capability is required in the future. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="SEC11-fsli-info" | <section anchor="SEC11-fsli-info" numbered="true" toc="default"> | |||
title="The fs_locations_info4 Structure"> | <name>The fs_locations_info4 Structure</name> | |||
<t> | <t> | |||
The fs_locations_info4 structure, encoding the fs_locations_info | The fs_locations_info4 structure, encoding the fs_locations_info | |||
attribute, contains the following: | attribute, contains the following: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
The fli_flags field, which contains general flags that affect | The fli_flags field, which contains general flags that affect | |||
the interpretation of this fs_locations_info4 structure and | the interpretation of this fs_locations_info4 structure and | |||
all fs_locations_item4 structures within it. The only flag | all fs_locations_item4 structures within it. The only flag | |||
currently defined is FSLI4IF_VAR_SUB. All bits in the | currently defined is FSLI4IF_VAR_SUB. All bits in the | |||
fli_flags field that are not defined should always be returned as zero. | fli_flags field that are not defined should always be returned as zero. | |||
</t> | </li> | |||
<t> | <li> | |||
The fli_fs_root field, which contains the pathname of the root of | The fli_fs_root field, which contains the pathname of the root of | |||
the current file system on the current server, just as it does | the current file system on the current server, just as it does | |||
in the fs_locations4 structure. | in the fs_locations4 structure. | |||
</t> | </li> | |||
<t> | <li> | |||
An array called fli_items of fs_locations4_item structures, which cont ain | An array called fli_items of fs_locations4_item structures, which cont ain | |||
information about replicas of the current file system. Where | information about replicas of the current file system. Where | |||
the current file system is actually present, or has been | the current file system is actually present, or has been | |||
present, i.e., this is not a referral situation, one of the | present, i.e., this is not a referral situation, one of the | |||
fs_locations_item4 structures will contain an fs_locations_server4 for | fs_locations_item4 structures will contain an fs_locations_server4 for | |||
the current server. This structure will have FSLI4GF_ABSENT set | the current server. This structure will have FSLI4GF_ABSENT set | |||
if the current file system is absent, i.e., normal access to it | if the current file system is absent, i.e., normal access to it | |||
will return NFS4ERR_MOVED. | will return NFS4ERR_MOVED. | |||
</t> | </li> | |||
<t> | <li> | |||
The fli_valid_for field specifies a time in seconds | The fli_valid_for field specifies a time in seconds | |||
for which it is reasonable for a client to use the fs_locations_info a ttribute | for which it is reasonable for a client to use the fs_locations_info a ttribute | |||
without refetch. The fli_valid_for value does not provide a | without refetch. The fli_valid_for value does not provide a | |||
guarantee of validity since servers can unexpectedly go out of | guarantee of validity since servers can unexpectedly go out of | |||
service or become inaccessible for any number of reasons. | service or become inaccessible for any number of reasons. | |||
Clients are well-advised to refetch this information for an | Clients are well-advised to refetch this information for an | |||
actively accessed file system at every fli_valid_for seconds. This | actively accessed file system at every fli_valid_for seconds. This | |||
is particularly important when file system replicas may go out | is particularly important when file system replicas may go out | |||
of service in a controlled way using the FSLI4GF_GOING flag to | of service in a controlled way using the FSLI4GF_GOING flag to | |||
communicate an ongoing change. The server should set | communicate an ongoing change. The server should set | |||
skipping to change at line 19061 ¶ | skipping to change at line 19149 ¶ | |||
different fli_valid_for value, which the client should then use | different fli_valid_for value, which the client should then use | |||
in the same fashion as the previous value. Because a refetch | in the same fashion as the previous value. Because a refetch | |||
of the attribute causes information from all component entries to | of the attribute causes information from all component entries to | |||
be refetched, the server will typically provide a low value for | be refetched, the server will typically provide a low value for | |||
this field if any of the replicas are likely to go out of service | this field if any of the replicas are likely to go out of service | |||
in a short time frame. Note that, because of the ability of the | in a short time frame. Note that, because of the ability of the | |||
server to return NFS4ERR_MOVED to trigger the use of different paths, | server to return NFS4ERR_MOVED to trigger the use of different paths, | |||
when alternate trunked paths are available, there is generally no | when alternate trunked paths are available, there is generally no | |||
need to use low values of fli_valid_for in connection with the | need to use low values of fli_valid_for in connection with the | |||
management of alternate paths to the same replica. | management of alternate paths to the same replica. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The FSLI4IF_VAR_SUB flag within fli_flags controls whether variable | The FSLI4IF_VAR_SUB flag within fli_flags controls whether variable | |||
substitution is to be enabled. See <xref target="SEC11-fsli-item" /> | substitution is to be enabled. See <xref target="SEC11-fsli-item" forma t="default"/> | |||
for an explanation of variable substitution. | for an explanation of variable substitution. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="SEC11-fsli-item" | <section anchor="SEC11-fsli-item" numbered="true" toc="default"> | |||
title="The fs_locations_item4 Structure"> | <name>The fs_locations_item4 Structure</name> | |||
<t> | <t> | |||
The fs_locations_item4 structure contains a pathname | The fs_locations_item4 structure contains a pathname | |||
(in the field fli_rootpath) that encodes | (in the field fli_rootpath) that encodes | |||
the path of the target file system replicas on the set of | the path of the target file system replicas on the set of | |||
servers designated by the included fs_locations_server4 entries. | servers designated by the included fs_locations_server4 entries. | |||
The precise manner in which this target location | The precise manner in which this target location | |||
is specified depends on the value of the FSLI4IF_VAR_SUB | is specified depends on the value of the FSLI4IF_VAR_SUB | |||
flag within the associated fs_locations_info4 structure. | flag within the associated fs_locations_info4 structure. | |||
</t> | </t> | |||
<t> | <t> | |||
If this flag is not set, then fli_rootpath simply designates | If this flag is not set, then fli_rootpath simply designates | |||
the location of the target file system within each server's | the location of the target file system within each server's | |||
single-server namespace just as it does for the rootpath | single-server namespace just as it does for the rootpath | |||
within the fs_location4 structure. When this bit is set, | within the fs_location4 structure. When this bit is set, | |||
however, component entries of a certain form are subject | however, component entries of a certain form are subject | |||
to client-specific variable substitution so as to allow | to client-specific variable substitution so as to allow | |||
a degree of namespace non-uniformity in order to accommodate | a degree of namespace non-uniformity in order to accommodate | |||
the selection of client-specific file system targets to | the selection of client-specific file system targets to | |||
adapt to different client architectures or other | adapt to different client architectures or other | |||
characteristics. | characteristics. | |||
</t> | </t> | |||
<t> | <t> | |||
When such substitution is in effect, a variable beginning | When such substitution is in effect, a variable beginning | |||
with the string "${" and ending with the string "}" | with the string "${" and ending with the string "}" | |||
and containing a colon is to be | and containing a colon is to be | |||
replaced by the client-specific value associated with | replaced by the client-specific value associated with | |||
that variable. The string "unknown" should be used | that variable. The string "unknown" should be used | |||
by the client when it has no value for such a variable. | by the client when it has no value for such a variable. | |||
The pathname resulting from such | The pathname resulting from such | |||
substitutions is used to designate the target file system, | substitutions is used to designate the target file system, | |||
so that different clients may have different file systems, | so that different clients may have different file systems, | |||
corresponding to that location in the multi-server namespace. | corresponding to that location in the multi-server namespace. | |||
</t> | </t> | |||
<t> | <t> | |||
As mentioned above, such substituted pathname variables | As mentioned above, such substituted pathname variables | |||
contain a colon. The part before the colon is to be a | contain a colon. The part before the colon is to be a | |||
DNS domain name, and the part after is to be a case-insensitive | DNS domain name, and the part after is to be a case-insensitive | |||
alphanumeric string. | alphanumeric string. | |||
</t> | </t> | |||
<t> | <t> | |||
Where the domain is "ietf.org", only variable names defined | Where the domain is "ietf.org", only variable names defined | |||
in this document or subsequent Standards Track RFCs | in this document or subsequent Standards Track RFCs | |||
are subject to such substitution. Organizations are | are subject to such substitution. Organizations are | |||
free to use their domain names to create their own sets | free to use their domain names to create their own sets | |||
of client-specific variables, to be subject to such | of client-specific variables, to be subject to such | |||
substitution. In cases where such variables are intended | substitution. In cases where such variables are intended | |||
to be used more broadly than a single organization, | to be used more broadly than a single organization, | |||
publication of an Informational RFC defining such variables | publication of an Informational RFC defining such variables | |||
is RECOMMENDED. | is <bcp14>RECOMMENDED</bcp14>. | |||
</t> | </t> | |||
<t> | <t> | |||
The variable ${ietf.org:CPU_ARCH} is used to denote that the | The variable ${ietf.org:CPU_ARCH} is used to denote that the | |||
CPU architecture object files are compiled. This specification | CPU architecture object files are compiled. This specification | |||
does not limit the acceptable values (except that they must be | does not limit the acceptable values (except that they must be | |||
valid UTF-8 strings), but such values as "x86", "x86_64", and "sparc" | valid UTF-8 strings), but such values as "x86", "x86_64", and "sparc" | |||
would be expected to be used in line with industry practice. | would be expected to be used in line with industry practice. | |||
</t> | </t> | |||
<t> | <t> | |||
The variable ${ietf.org:OS_TYPE} is used to denote the | The variable ${ietf.org:OS_TYPE} is used to denote the | |||
operating system, and thus the kernel and library APIs, | operating system, and thus the kernel and library APIs, | |||
for which code might be compiled. This specification does | for which code might be compiled. This specification does | |||
not limit the acceptable values (except that they must be | not limit the acceptable values (except that they must be | |||
valid UTF-8 strings), but such values as "linux" and "freebsd" | valid UTF-8 strings), but such values as "linux" and "freebsd" | |||
would be expected to be used in line with industry practice. | would be expected to be used in line with industry practice. | |||
</t> | </t> | |||
<t> | <t> | |||
The variable ${ietf.org:OS_VERSION} is used to denote the | The variable ${ietf.org:OS_VERSION} is used to denote the | |||
operating system version, and thus the specific details | operating system version, and thus the specific details | |||
of versioned interfaces, | of versioned interfaces, | |||
for which code might be compiled. This specification does | for which code might be compiled. This specification does | |||
not limit the acceptable values (except that they must be | not limit the acceptable values (except that they must be | |||
valid UTF-8 strings). However, combinations of numbers and | valid UTF-8 strings). However, combinations of numbers and | |||
letters with interspersed dots would be expected to be used | letters with interspersed dots would be expected to be used | |||
in line with industry practice, with the details of the | in line with industry practice, with the details of the | |||
version format depending on the specific value of | version format depending on the specific value of | |||
the variable ${ietf.org:OS_TYPE} with which | the variable ${ietf.org:OS_TYPE} with which | |||
it is used. | it is used. | |||
</t> | </t> | |||
<t> | <t> | |||
Use of these variables could result in the direction of different | Use of these variables could result in the direction of different | |||
clients to different file systems on the same server, as | clients to different file systems on the same server, as | |||
appropriate to particular clients. In cases in which the | appropriate to particular clients. In cases in which the | |||
target file systems are located on different servers, a single | target file systems are located on different servers, a single | |||
server could serve as a referral point so that each valid | server could serve as a referral point so that each valid | |||
combination of variable values would designate a referral | combination of variable values would designate a referral | |||
hosted on a single server, with the targets of those referrals on | hosted on a single server, with the targets of those referrals on | |||
a number of different servers. | a number of different servers. | |||
</t> | </t> | |||
<t> | <t> | |||
Because namespace administration is affected by the values | Because namespace administration is affected by the values | |||
selected to substitute for various variables, clients should | selected to substitute for various variables, clients should | |||
provide convenient means of determining what variable | provide convenient means of determining what variable | |||
substitutions a client will implement, as well as, where | substitutions a client will implement, as well as, where | |||
appropriate, providing means to control the substitutions to | appropriate, providing means to control the substitutions to | |||
be used. The exact means by which this will be done is | be used. The exact means by which this will be done is | |||
outside the scope of this specification. | outside the scope of this specification. | |||
</t> | </t> | |||
<t> | <t> | |||
Although variable substitution is most suitable for use | Although variable substitution is most suitable for use | |||
in the context of referrals, it may be used in the context | in the context of referrals, it may be used in the context | |||
of replication and migration. If it is used in these contexts, | of replication and migration. If it is used in these contexts, | |||
the server must ensure that no matter what values the | the server must ensure that no matter what values the | |||
client presents for the substituted variables, the result | client presents for the substituted variables, the result | |||
is always a valid successor file system instance to that | is always a valid successor file system instance to that | |||
from which a transition is occurring, i.e., that the data is | from which a transition is occurring, i.e., that the data is | |||
identical or represents a later image of a writable file | identical or represents a later image of a writable file | |||
system. | system. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that when fli_rootpath is a null pathname (that is, one | Note that when fli_rootpath is a null pathname (that is, one | |||
with zero components), the file system designated is at the | with zero components), the file system designated is at the | |||
root of the specified server, whether or not the FSLI4IF_VAR_SUB | root of the specified server, whether or not the FSLI4IF_VAR_SUB | |||
flag within the associated fs_locations_info4 structure is | flag within the associated fs_locations_info4 structure is | |||
set. | set. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="fs_status" | <section anchor="fs_status" numbered="true" toc="default"> | |||
title="The Attribute fs_status"> | <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="xdr"><![CDATA[ | ||||
<figure> | ||||
<artwork> | ||||
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; | |||
fs4_status_type fss_type; | fs4_status_type fss_type; | |||
utf8str_cs fss_source; | utf8str_cs fss_source; | |||
utf8str_cs fss_current; | utf8str_cs fss_current; | |||
int32_t fss_age; | int32_t fss_age; | |||
nfstime4 fss_version; | nfstime4 fss_version; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
<t> | ||||
The boolean fss_absent indicates whether the file system is | The boolean fss_absent indicates whether the file system is | |||
currently absent. This value will be set if the file system was | currently absent. This value will be set if the file system was | |||
previously present and becomes absent, or if the file system has | previously present and becomes absent, or if the file system has | |||
never been present and the type is STATUS4_REFERRAL. When this | never been present and the type is STATUS4_REFERRAL. When this | |||
boolean is set and the type is not STATUS4_REFERRAL, the | boolean is set and the type is not STATUS4_REFERRAL, the | |||
remaining information in the fs4_status reflects that last valid | remaining information in the fs4_status reflects that last valid | |||
when the file system was present. | when the file system was present. | |||
</t> | </t> | |||
<t> | <t> | |||
The fss_type field indicates the kind of file system image represented. | The fss_type field indicates the kind of file system image represented. | |||
This is of particular importance when using the version values to | This is of particular importance when using the version values to | |||
determine appropriate succession of file system images. | determine appropriate succession of file system images. | |||
When fss_absent is set, and the file system was previously | When fss_absent is set, and the file system was previously | |||
present, the value of fss_type reflected is that when the file was last pr esent. | present, the value of fss_type reflected is that when the file was last pr esent. | |||
Five values are distinguished: | Five values are distinguished: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style='symbols'> | <li> | |||
<t> | ||||
STATUS4_FIXED, which indicates a read-only image in the sense | STATUS4_FIXED, which indicates a read-only image in the sense | |||
that it will never change. The possibility is allowed that, as | that it will never change. The possibility is allowed that, as | |||
a result of migration or switch to a different image, changed | a result of migration or switch to a different image, changed | |||
data can be accessed, but within the confines of this instance, | data can be accessed, but within the confines of this instance, | |||
no change is allowed. The client can use this fact to | no change is allowed. The client can use this fact to | |||
cache aggressively. | cache aggressively. | |||
</t> | </li> | |||
<t> | <li> | |||
STATUS4_VERSIONED, which indicates that the image, like the | STATUS4_VERSIONED, which indicates that the image, like the | |||
STATUS4_UPDATED case, is updated externally, but it provides | STATUS4_UPDATED case, is updated externally, but it provides | |||
a guarantee that the server will carefully update an | a guarantee that the server will carefully update an | |||
associated version value so that the client can | associated version value so that the client can | |||
protect itself from a situation in which it reads | protect itself from a situation in which it reads | |||
data from one version of the file system and then later reads | data from one version of the file system and then later reads | |||
data from an earlier version of the same file system. See | data from an earlier version of the same file system. See | |||
below for a discussion of how this can be done. | below for a discussion of how this can be done. | |||
</t> | </li> | |||
<t> | <li> | |||
STATUS4_UPDATED, which indicates an image that cannot be | STATUS4_UPDATED, which indicates an image that cannot be | |||
updated by the user writing to it but that may be changed | updated by the user writing to it but that may be changed | |||
externally, typically because it is a periodically updated | externally, typically because it is a periodically updated | |||
copy of another writable file system somewhere else. In | copy of another writable file system somewhere else. In | |||
this case, version information is not provided, and the | this case, version information is not provided, and the | |||
client does not have the responsibility of making sure | client does not have the responsibility of making sure | |||
that this version only advances upon a file system instance | that this version only advances upon a file system instance | |||
transition. In this case, it is the responsibility of the | transition. In this case, it is the responsibility of the | |||
server to make sure that the data presented after a file | server to make sure that the data presented after a file | |||
system instance transition is a proper successor image and | system instance transition is a proper successor image and | |||
includes all changes seen by the client and any change made | includes all changes seen by the client and any change made | |||
before all such changes. | before all such changes. | |||
</t> | </li> | |||
<t> | <li> | |||
STATUS4_WRITABLE, which indicates that the file system is an | STATUS4_WRITABLE, which indicates that the file system is an | |||
actual writable one. The client need not, of course, actually | actual writable one. The client need not, of course, actually | |||
write to the file system, but once it does, it should not | write to the file system, but once it does, it should not | |||
accept a transition to anything other than a writable instance | accept a transition to anything other than a writable instance | |||
of that same file system. | of that same file system. | |||
</t> | </li> | |||
<t> | <li> | |||
STATUS4_REFERRAL, which indicates that the file system in | STATUS4_REFERRAL, which indicates that the file system in | |||
question is absent and has never been present on this | question is absent and has never been present on this | |||
server. | server. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Note that in the STATUS4_UPDATED and STATUS4_VERSIONED cases, the | Note that in the STATUS4_UPDATED and STATUS4_VERSIONED cases, the | |||
server is responsible for the appropriate handling of locks that | server is responsible for the appropriate handling of locks that | |||
are inconsistent with external changes to delegations. | are inconsistent with external changes to delegations. | |||
If a server gives out delegations, they SHOULD be recalled | If a server gives out delegations, they <bcp14>SHOULD</bcp14> be recalled | |||
before an inconsistent change is made to the data, and MUST | before an inconsistent change is made to the data, and <bcp14>MUST</bcp14> | |||
be revoked if this is not possible. Similarly, if an OPEN is | be revoked if this is not possible. Similarly, if an OPEN is | |||
inconsistent with data that is changed (the OPEN has | inconsistent with data that is changed (the OPEN has | |||
OPEN4_SHARE_DENY_WRITE/OPEN4_SHARE_DENY_BOTH | OPEN4_SHARE_DENY_WRITE/OPEN4_SHARE_DENY_BOTH | |||
and the data is changed), that OPEN SHOULD be considered | and the data is changed), that OPEN <bcp14>SHOULD</bcp14> be considered | |||
administratively revoked. | administratively revoked. | |||
</t> | </t> | |||
<t> | <t> | |||
The opaque strings fss_source and fss_current provide a way of presenting | The opaque strings fss_source and fss_current provide a way of presenting | |||
information about the source of the file system image being present. | information about the source of the file system image being present. | |||
It is not intended that the client do anything with this information | It is not intended that the client do anything with this information | |||
other than make it available to administrative tools. It is | other than make it available to administrative tools. It is | |||
intended that this information be helpful when researching possible | intended that this information be helpful when researching possible | |||
problems with a file system image that might arise when it is | problems with a file system image that might arise when it is | |||
unclear if the correct image is being accessed and, if not, how that | unclear if the correct image is being accessed and, if not, how that | |||
image came to be made. This kind of diagnostic information will be | image came to be made. This kind of diagnostic information will be | |||
helpful, if, as seems likely, copies of file systems are made in | helpful, if, as seems likely, copies of file systems are made in | |||
many different ways (e.g., simple user-level copies, | many different ways (e.g., simple user-level copies, | |||
file-system-level point-in-time copies, | file-system-level point-in-time copies, | |||
clones of the underlying storage), | clones of the underlying storage), | |||
under a variety of administrative arrangements. In such | under a variety of administrative arrangements. In such | |||
environments, determining how a given set of data was constructed | environments, determining how a given set of data was constructed | |||
can be very helpful in resolving problems. | can be very helpful in resolving problems. | |||
</t> | </t> | |||
<t> | <t> | |||
The opaque string fss_source is used to indicate the source of a | The opaque string fss_source is used to indicate the source of a | |||
given file system with the expectation that tools capable of | given file system with the expectation that tools capable of | |||
creating a file system image propagate this information, when | creating a file system image propagate this information, when | |||
possible. It is understood that this may not always be possible | possible. It is understood that this may not always be possible | |||
since a user-level copy may be thought of as creating a new data | since a user-level copy may be thought of as creating a new data | |||
set and the tools used may have no mechanism to propagate this | set and the tools used may have no mechanism to propagate this | |||
data. When a file system is initially created, it is desirable | data. When a file system is initially created, it is desirable | |||
to associate with it | to associate with it | |||
data regarding how the file system was created, where it was | data regarding how the file system was created, where it was | |||
created, who created it, etc. Making this information available | created, who created it, etc. Making this information available | |||
in this attribute in a human-readable | in this attribute in a human-readable | |||
string will be helpful for applications and | string will be helpful for applications and | |||
system administrators and will also serve to make it available when | system administrators and will also serve to make it available when | |||
the original file system is used to make subsequent copies. | the original file system is used to make subsequent copies. | |||
</t> | </t> | |||
<t> | <t> | |||
The opaque string fss_current should provide whatever information is | The opaque string fss_current should provide whatever information is | |||
available about the source of the current copy. Such | available about the source of the current copy. Such | |||
information includes | information includes | |||
the tool creating it, any relevant parameters to that tool, the | the tool creating it, any relevant parameters to that tool, the | |||
time at which the copy was done, the user making the change, the | time at which the copy was done, the user making the change, the | |||
server on which the change was made, etc. All information should be | server on which the change was made, etc. All information should be | |||
in a human-readable string. | in a human-readable string. | |||
</t> | </t> | |||
<t> | <t> | |||
The field fss_age provides an indication of how out-of-date the file syste m | The field fss_age provides an indication of how out-of-date the file syste m | |||
currently is with respect to its ultimate data source (in case of | currently is with respect to its ultimate data source (in case of | |||
cascading data updates). This complements the fls_currency field of | cascading data updates). This complements the fls_currency field of | |||
fs_locations_server4 (see <xref target='SEC11-li-new' />) in the | fs_locations_server4 (see <xref target="SEC11-li-new" format="default"/>) in the | |||
following way: the information in fls_currency | following way: the information in fls_currency | |||
gives a bound for how out of date the data in a file system might | gives a bound for how out of date the data in a file system might | |||
typically get, while the value in fss_age gives a bound on how out-of-date that | typically get, while the value in fss_age gives a bound on how out-of-date that | |||
data actually is. Negative values imply that no information is | data actually is. Negative values imply that no information is | |||
available. A zero means that this data is known to be current. | available. A zero means that this data is known to be current. | |||
A positive value means that this data is known to be no older than | A positive value means that this data is known to be no older than | |||
that number of seconds with respect to the ultimate data source. | that number of seconds with respect to the ultimate data source. | |||
Using this value, the client may be able to decide that a data copy | Using this value, the client may be able to decide that a data copy | |||
is too old, so that it may search for a newer version to use. | is too old, so that it may search for a newer version to use. | |||
</t> | </t> | |||
<t> | <t> | |||
The fss_version field provides a version identification, in the form of | The fss_version field provides a version identification, in the form of | |||
a time value, such that successive versions always have later time | a time value, such that successive versions always have later time | |||
values. When the fs_type is anything other than | values. When the fs_type is anything other than | |||
STATUS4_VERSIONED, the server may provide such a value, but there is | STATUS4_VERSIONED, the server may provide such a value, but there is | |||
no guarantee as to its validity and clients will not use it except | no guarantee as to its validity and clients will not use it except | |||
to provide additional information to add to fss_source and fss_current. | to provide additional information to add to fss_source and fss_current. | |||
</t> | </t> | |||
<t> | <t> | |||
When fss_type is STATUS4_VERSIONED, servers SHOULD provide a value | When fss_type is STATUS4_VERSIONED, servers <bcp14>SHOULD</bcp14> provide | |||
a value | ||||
of fss_version that progresses monotonically whenever any new version | of fss_version that progresses monotonically whenever any new version | |||
of the data is established. This allows the client, if reliable | of the data is established. This allows the client, if reliable | |||
image progression is important to it, to fetch this attribute as | image progression is important to it, to fetch this attribute as | |||
part of each COMPOUND where data or metadata from the file system is | part of each COMPOUND where data or metadata from the file system is | |||
used. | used. | |||
</t> | </t> | |||
<t> | <t> | |||
When it is important to the client to make sure that only valid | When it is important to the client to make sure that only valid | |||
successor images are accepted, it must make sure that it does not | successor images are accepted, it must make sure that it does not | |||
read data or metadata from the file system without updating its | read data or metadata from the file system without updating its | |||
sense of the current state of the image. This is to avoid the possibility | sense of the current state of the image. This is to avoid the possibility | |||
that the fs_status that the client holds will be one for an | that the fs_status that the client holds will be one for an | |||
earlier image, which would cause the client to accept a new file | earlier image, which would cause the client to accept a new file | |||
system instance that is later than that but still earlier than | system instance that is later than that but still earlier than | |||
the updated data read by the client. | the updated data read by the client. | |||
</t> | </t> | |||
<t> | <t> | |||
In order to accept valid images reliably, the client must do a GETATTR of the fs_status | In order to accept valid images reliably, the client must do a GETATTR of the fs_status | |||
attribute that follows any interrogation of data or metadata within the | attribute that follows any interrogation of data or metadata within the | |||
file system in question. Often this is most conveniently done by | file system in question. Often this is most conveniently done by | |||
appending such a GETATTR after all other operations that reference | appending such a GETATTR after all other operations that reference | |||
a given file system. When errors occur between reading file system | a given file system. When errors occur between reading file system | |||
data and performing such a GETATTR, care must be exercised to make | data and performing such a GETATTR, care must be exercised to make | |||
sure that the data in question is not used before obtaining the | sure that the data in question is not used before obtaining the | |||
proper fs_status value. In this connection, when an OPEN is done | proper fs_status value. In this connection, when an OPEN is done | |||
within such a versioned file system and the associated GETATTR of | within such a versioned file system and the associated GETATTR of | |||
fs_status is not successfully completed, the open file in question | fs_status is not successfully completed, the open file in question | |||
must not be accessed until that fs_status is fetched. | must not be accessed until that fs_status is fetched. | |||
</t> | </t> | |||
<t> | <t> | |||
The procedure above will ensure that before using any data from the | The procedure above will ensure that before using any data from the | |||
file system the client has in hand a newly-fetched current version | file system the client has in hand a newly-fetched current version | |||
of the file system image. Multiple values for multiple requests in | of the file system image. Multiple values for multiple requests in | |||
flight can be resolved by assembling them into the required partial | flight can be resolved by assembling them into the required partial | |||
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 tha n the | an fss_type of STATUS4_VERSIONED or whose fss_version field is earlier tha n 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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ | <section anchor="pnfs" numbered="true" toc="default"> | |||
--> | <name>Parallel NFS (pNFS)</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section anchor="pnfs_intro" numbered="true" toc="default"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>Introduction</name> | |||
<section title="Parallel NFS (pNFS)" anchor="pnfs"> | <t> | |||
<section title="Introduction" anchor="pnfs_intro"> | pNFS is an <bcp14>OPTIONAL</bcp14> feature within NFSv4.1; the pNFS feature | |||
<t> | ||||
pNFS is an OPTIONAL 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 | |||
better file access performance. The relationship among multiple | better file access performance. The relationship among multiple | |||
clients, a single server, and multiple storage devices for pNFS | clients, a single server, and multiple storage devices for pNFS | |||
(server and clients have access to all storage devices) is shown in | (server and clients have access to all storage devices) is shown in | |||
<xref target="fig_system"/>. | <xref target="fig_system" format="default"/>. | |||
</t> | </t> | |||
<figure anchor="fig_system"> | <figure anchor="fig_system"> | |||
<artwork><![CDATA[ | <artwork name="" type="" align="left" alt=""><![CDATA[ | |||
+-----------+ | +-----------+ | |||
|+-----------+ +-----------+ | |+-----------+ +-----------+ | |||
||+-----------+ | | | ||+-----------+ | | | |||
||| | NFSv4.1 + pNFS | | | ||| | NFSv4.1 + pNFS | | | |||
+|| Clients |<------------------------------>| Server | | +|| Clients |<------------------------------>| Server | | |||
+| | | | | +| | | | | |||
+-----------+ | | | +-----------+ | | | |||
||| +-----------+ | ||| +-----------+ | |||
||| | | ||| | | |||
||| | | ||| | | |||
||| Storage +-----------+ | | ||| Storage +-----------+ | | |||
||| Protocol |+-----------+ | | ||| Protocol |+-----------+ | | |||
||+----------------||+-----------+ Control | | ||+----------------||+-----------+ Control | | |||
|+-----------------||| | Protocol| | |+-----------------||| | Protocol| | |||
+------------------+|| Storage |------------+ | +------------------+|| Storage |------------+ | |||
+| Devices | | +| Devices | | |||
+-----------+ | +-----------+ | |||
]]></artwork> | ]]></artwork> | |||
</figure> | </figure> | |||
<t> | <t> | |||
In this model, the clients, server, and storage devices are | In this model, the clients, server, and storage devices are | |||
responsible for managing file access. This is in contrast to NFSv4 | responsible for managing file access. This is in contrast to NFSv4 | |||
without pNFS, where it is primarily the server's responsibility; some | without pNFS, where it is primarily the server's responsibility; some | |||
of this responsibility may be delegated to the client under strictly | of this responsibility may be delegated to the client under strictly | |||
specified conditions. See <xref target="storage_protocol"/> | specified conditions. See <xref target="storage_protocol" format="default"/> | |||
for a discussion of the Storage Protocol. See <xref target="control_protocol"/ | for a discussion of the Storage Protocol. See <xref target="control_protocol" | |||
> for a | format="default"/> for a | |||
discussion of the Control Protocol. | discussion of the Control Protocol. | |||
</t> | </t> | |||
<t> | <t> | |||
pNFS takes the form of OPTIONAL operations that manage protocol | pNFS takes the form of <bcp14>OPTIONAL</bcp14> operations that manage protocol | |||
objects called 'layouts' (<xref target="layout_types"/>) that | objects called 'layouts' (<xref target="layout_types" format="default"/>) that | |||
contain a byte-range and storage location information. The layout | contain a byte-range and storage location information. The layout | |||
is managed in a similar fashion | is managed in a similar fashion | |||
as NFSv4.1 data delegations. For example, the layout is leased, | as NFSv4.1 data delegations. For example, the layout is leased, | |||
recallable, and revocable. However, layouts are distinct abstractions | recallable, and revocable. However, layouts are distinct abstractions | |||
and are manipulated with new operations. When a client holds a | and are manipulated with new operations. When a client holds a | |||
layout, it is granted the ability to directly access the byte-range | layout, it is granted the ability to directly access the byte-range | |||
at the storage location specified in the layout. | at the storage location specified in the layout. | |||
</t> | </t> | |||
<t> | <t> | |||
There are interactions between layouts and other NFSv4.1 | There are interactions between layouts and other NFSv4.1 | |||
abstractions such as data delegations and byte-range locking. | abstractions such as data delegations and byte-range locking. | |||
Delegation issues are discussed in <xref | Delegation issues are discussed in <xref target="recalling_layout" format="def | |||
target="recalling_layout"/>. Byte-range locking issues are | ault"/>. Byte-range locking issues are | |||
discussed in Sections <xref target="layout_iomode" format="counter" /> and <xr | discussed in Sections <xref target="layout_iomode" format="counter"/> and <xre | |||
ef | f target="layout_semantics" format="counter"/>. | |||
target="layout_semantics" format="counter" />. | ||||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="pNFS Definitions"> | <name>pNFS Definitions</name> | |||
<t> | <t> | |||
NFSv4.1's pNFS feature provides parallel data access to a | NFSv4.1's pNFS feature provides parallel data access to a | |||
file system that stripes its content across multiple | file system that stripes its content across multiple | |||
storage servers. The first instantiation of pNFS, as | storage servers. The first instantiation of pNFS, as | |||
part of NFSv4.1, separates the file system protocol | part of NFSv4.1, separates the file system protocol | |||
processing into two parts: metadata processing and data | processing into two parts: metadata processing and data | |||
processing. Data consist of the contents of regular | processing. Data consist of the contents of regular | |||
files that are striped across storage servers. Data | files that are striped across storage servers. Data | |||
striping occurs in at least two ways: on a file-by-file | striping occurs in at least two ways: on a file-by-file | |||
basis and, within sufficiently large files, on a | basis and, within sufficiently large files, on a | |||
block-by-block basis. In contrast, striped access to | block-by-block basis. In contrast, striped access to | |||
metadata by pNFS clients is not provided in NFSv4.1, even | metadata by pNFS clients is not provided in NFSv4.1, even | |||
though the file system back end of a pNFS server might | though the file system back end of a pNFS server might | |||
stripe metadata. Metadata consist of everything else, | stripe metadata. Metadata consist of everything else, | |||
including the contents of non-regular files (e.g., | including the contents of non-regular files (e.g., | |||
directories); see <xref target="metadata"/>. The | directories); see <xref target="metadata" format="default"/>. The | |||
metadata functionality is implemented by an NFSv4.1 | metadata functionality is implemented by an NFSv4.1 | |||
server that supports pNFS and the operations described in | server that supports pNFS and the operations described in | |||
<xref target="nfsv41operations" />; such a server is | <xref target="nfsv41operations" format="default"/>; such a server is | |||
called a metadata server (<xref target="mds"/>). | called a metadata server (<xref target="mds" format="default"/>). | |||
</t> | </t> | |||
<t> | <t> | |||
The data functionality is implemented by one or more storage devices, each of which | The data functionality is implemented by one or more storage devices, each of which | |||
are accessed by the client via a storage protocol. A subset (defined in <xref | are accessed by the client via a storage protocol. A subset (defined in <xref | |||
target="ds_ops" | target="ds_ops" format="default"/>) of NFSv4.1 is one such storage protocol. N | |||
/>) of NFSv4.1 is one such storage protocol. New terms are | ew terms are | |||
introduced to the NFSv4.1 nomenclature and existing terms are | introduced to the NFSv4.1 nomenclature and existing terms are | |||
clarified to allow for the description of the pNFS feature. | clarified to allow for the description of the pNFS feature. | |||
</t> | </t> | |||
<section anchor="metadata" numbered="true" toc="default"> | ||||
<section title="Metadata" anchor="metadata"> | <name>Metadata</name> | |||
<t> | <t> | |||
Information about a file system object, such as its name, location | Information about a file system object, such as its name, location | |||
within the namespace, owner, ACL, and other attributes. Metadata may | within the namespace, owner, ACL, and other attributes. Metadata may | |||
also include storage location information, and this will vary based | also include storage location information, and this will vary based | |||
on the underlying storage mechanism that is used. | on the underlying storage mechanism that is used. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="mds" numbered="true" toc="default"> | ||||
<section title="Metadata Server" anchor="mds"> | <name>Metadata Server</name> | |||
<t> | <t> | |||
An NFSv4.1 server that supports the pNFS feature. A variety of | An NFSv4.1 server that supports the pNFS feature. A variety of | |||
architectural choices exist for the metadata server and its use of | architectural choices exist for the metadata server and its use of | |||
file system information held at the server. Some servers may | file system information held at the server. Some servers may | |||
contain metadata only for file objects residing at the | contain metadata only for file objects residing at the | |||
metadata server, while the file data resides on associated storage | metadata server, while the file data resides on associated storage | |||
devices. Other metadata servers may hold both metadata and a | devices. Other metadata servers may hold both metadata and a | |||
varying degree of file data. | varying degree of file data. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="pNFS Client"> | <name>pNFS Client</name> | |||
<t> | <t> | |||
An NFSv4.1 client that supports pNFS operations and supports at | An NFSv4.1 client that supports pNFS operations and supports at | |||
least one storage protocol for performing I/O | least one storage protocol for performing I/O | |||
to storage devices. | to storage devices. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="Storage Device"> | <name>Storage Device</name> | |||
<t> | <t> | |||
A storage device stores a regular file's data, but leaves metadata | A storage device stores a regular file's data, but leaves metadata | |||
management to the metadata server. A storage device could be | management to the metadata server. A storage device could be | |||
another NFSv4.1 server, an object-based storage device (OSD), | another NFSv4.1 server, an object-based storage device (OSD), | |||
a block | a block | |||
device accessed over a System Area Network (SAN, e.g., either | device accessed over a System Area Network (SAN, e.g., either | |||
FiberChannel or iSCSI SAN), or some other entity. | FiberChannel or iSCSI SAN), or some other entity. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="storage_protocol" numbered="true" toc="default"> | ||||
<section anchor="storage_protocol" title="Storage Protocol"> | <name>Storage Protocol</name> | |||
<t> | <t> | |||
As noted in <xref | As noted in <xref target="fig_system" format="default"/>, | |||
target="fig_system"/>, | ||||
the storage protocol is the method used by the client to | the storage protocol is the method used by the client to | |||
store and retrieve data directly from the storage devices. | store and retrieve data directly from the storage devices. | |||
</t> | </t> | |||
<t> | <t> | |||
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 <xref | One example storage protocol is NFSv4.1 itself (as documented in | |||
target="file_layout_type"/>). Other options for the storage protocol | <xref target="file_layout_type" format="default"/>). Other options for the st | |||
orage protocol | ||||
are described elsewhere and include: | are described elsewhere and include: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
Block/volume protocols such as Internet SCSI (iSCSI) <xref target="RFC3720 | <li> | |||
" | Block/volume protocols such as Internet SCSI (iSCSI) | |||
/> and FCP <xref target="FCP-2" />. The block/volume | <xref target="RFC7143" format="default"/> and FCP <xref target="FCP-2" for | |||
mat="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"/> 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. | |||
</t> | </li> | |||
<t> | <li> | |||
Object protocols such as OSD over iSCSI or Fibre Channel <xref | Object protocols such as OSD over iSCSI or Fibre Channel <xref target="OSD | |||
target="OSD-T10" />. See | -T10" format="default"/>. See | |||
<xref target="RFC5664"/> for a layout specification | <xref target="RFC5664" format="default"/> for a layout specification | |||
that allows pNFS to use object storage protocols. | that allows pNFS to use object storage protocols. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
It is possible that various storage protocols are available to | It is possible that various storage protocols are available to | |||
both client and server and it may be possible that a client and | both client and server and it may be possible that a client and | |||
server do not have a matching storage protocol available to them. | server do not have a matching storage protocol available to them. | |||
Because of this, the pNFS server MUST support normal NFSv4.1 access | Because of this, the pNFS server <bcp14>MUST</bcp14> support normal NFSv4.1 ac cess | |||
to any file accessible by the pNFS feature; this will allow for | to any file accessible by the pNFS feature; this will allow for | |||
continued interoperability between an NFSv4.1 client and server. | continued interoperability between an NFSv4.1 client and server. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="control_protocol" numbered="true" toc="default"> | ||||
<section anchor="control_protocol" title="Control Protocol"> | <name>Control Protocol</name> | |||
<t> | <t> | |||
As noted in <xref | As noted in <xref target="fig_system" format="default"/>, | |||
target="fig_system"/>, | ||||
the control protocol is used by the exported file system between the | the control protocol is used by the exported file system between the | |||
metadata server and storage devices. Specification of such | metadata server and storage devices. Specification of such | |||
protocols is outside the scope of the NFSv4.1 protocol. Such | protocols is outside the scope of the NFSv4.1 protocol. Such | |||
control protocols would be used to control activities such as the | control protocols would be used to control activities such as the | |||
allocation and deallocation of storage, the management of state | allocation and deallocation of storage, the management of state | |||
required by the storage devices to perform client access control, | required by the storage devices to perform client access control, | |||
and, depending on the storage protocol, the enforcement of | and, depending on the storage protocol, the enforcement of | |||
authentication and authorization so that restrictions that | authentication and authorization so that restrictions that | |||
would be enforced by the metadata server are also enforced by | would be enforced by the metadata server are also enforced by | |||
the storage device. | the storage device. | |||
</t> | </t> | |||
<t> | <t> | |||
A particular control protocol is not REQUIRED by NFSv4.1 but | A particular control protocol is not <bcp14>REQUIRED</bcp14> by NFSv4.1 but | |||
requirements are placed on the control protocol for maintaining | requirements are placed on the control protocol for maintaining | |||
attributes like modify time, the change attribute, and the end-of-file | attributes like modify time, the change attribute, and the end-of-file | |||
(EOF) position. Note that if pNFS is layered over a clustered, parallel | (EOF) position. Note that if pNFS is layered over a clustered, parallel | |||
file system (e.g., <xref target="PVFS">PVFS</xref>), the mechanisms that | file system (e.g., <xref target="PVFS" format="default">PVFS</xref>), the mech anisms that | |||
enable clustering and parallelism in that file system can be considered | enable clustering and parallelism in that file system can be considered | |||
the control protocol. | the control protocol. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="layout_types" numbered="true" toc="default"> | ||||
<section anchor="layout_types" title="Layout Types"> | <name>Layout Types</name> | |||
<t> | <t> | |||
A layout describes the mapping of a file's data to the storage | A layout describes the mapping of a file's data to the storage | |||
devices that hold the data. A layout is said to belong to a | devices that hold the data. A layout is said to belong to a | |||
specific layout type (data type layouttype4, see <xref | specific layout type (data type layouttype4, see <xref target="layouttype4" fo | |||
target="layouttype4" />). The layout type allows for variants to | rmat="default"/>). The layout type allows for variants to | |||
handle different storage protocols, such as those associated with | handle different storage protocols, such as those associated with | |||
block/volume <xref target="RFC5663" />, object <xref | block/volume <xref target="RFC5663" format="default"/>, object <xref target="R | |||
target="RFC5664" />, and file (<xref target="file_layout_type" | FC5664" format="default"/>, and file (<xref target="file_layout_type" format="de | |||
/>) layout types. A metadata server, along with its control | fault"/>) layout types. A metadata server, along with its control | |||
protocol, MUST support at least one layout type. A private | protocol, <bcp14>MUST</bcp14> support at least one layout type. A private | |||
sub-range of the layout type namespace is also defined. Values from | sub-range of the layout type namespace is also defined. Values from | |||
the private layout type range MAY be used for internal testing or | the private layout type range <bcp14>MAY</bcp14> be used for internal testing | |||
experimentation (see <xref target="layouttype4"/>). | or | |||
experimentation (see <xref target="layouttype4" format="default"/>). | ||||
</t> | </t> | |||
<t> | <t> | |||
As an example, the organization of the file layout type could be | As an example, the organization of the file layout type could be | |||
an array of tuples (e.g., device ID, filehandle), along with a | an array of tuples (e.g., device ID, filehandle), along with a | |||
definition of how the data is | definition of how the data is | |||
stored across the devices (e.g., striping). A block/volume layout | stored across the devices (e.g., striping). A block/volume layout | |||
might be an array of tuples that store <device ID, block number, | might be an array of tuples that store <device ID, block number, | |||
block count> | block count> | |||
along with information about block size and the | along with information about block size and the | |||
associated file offset of the block number. An object layout might | associated file offset of the block number. An object layout might | |||
be an array of tuples <device ID, object ID> and an additional | be an array of tuples <device ID, object ID> and an additional | |||
structure (i.e., the aggregation map) that defines how the logical | structure (i.e., the aggregation map) that defines how the logical | |||
byte sequence of the file data is serialized into the different | byte sequence of the file data is serialized into the different | |||
objects. Note that the actual layouts are typically more complex | objects. Note that the actual layouts are typically more complex | |||
than these simple expository examples. | than these simple expository examples. | |||
</t> | </t> | |||
<t> | <t> | |||
Requests for pNFS-related operations will often specify a layout | Requests for pNFS-related operations will often specify a layout | |||
type. Examples of such operations are GETDEVICEINFO and LAYOUTGET. | type. Examples of such operations are GETDEVICEINFO and LAYOUTGET. | |||
The response for these operations will include structures such | The response for these operations will include structures such | |||
as a device_addr4 or a layout4, each of which includes a layout type within | as a device_addr4 or a layout4, each of which includes a layout type within | |||
it. The layout type sent by the server MUST always be the same | it. The layout type sent by the server <bcp14>MUST</bcp14> always be the same | |||
one requested by the client. When a server sends a response that | one requested by the client. When a server sends a response that | |||
includes a different layout type, the client SHOULD ignore the | includes a different layout type, the client <bcp14>SHOULD</bcp14> ignore the | |||
response and behave as if the server had returned an error response. | response and behave as if the server had returned an error response. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="layout" numbered="true" toc="default"> | ||||
<section title="Layout" anchor="layout"> | <name>Layout</name> | |||
<t> | <t> | |||
A layout defines how a file's data is organized on one or more | A layout defines how a file's data is organized on one or more | |||
storage devices. There are many potential layout types; each of the | storage devices. There are many potential layout types; each of the | |||
layout types are differentiated by the storage protocol used to | layout types are differentiated by the storage protocol used to | |||
access data and by the aggregation scheme that lays out the file | access data and by the aggregation scheme that lays out the file | |||
data on the underlying storage devices. A layout is precisely | data on the underlying storage devices. A layout is precisely | |||
identified by the tuple <client ID, filehandle, layout | identified by the tuple <client ID, filehandle, layout | |||
type, iomode, range>, where filehandle refers to the filehandle | type, iomode, range>, where filehandle refers to the filehandle | |||
of the file on the metadata server. | of the file on the metadata server. | |||
</t> | </t> | |||
<t> | <t> | |||
It is important to define when layouts overlap and/or conflict with | It is important to define when layouts overlap and/or conflict with | |||
each other. For two layouts with overlapping byte-ranges to | each other. For two layouts with overlapping byte-ranges to | |||
actually overlap each other, both layouts must be of the same layout | actually overlap each other, both layouts must be of the same layout | |||
type, correspond to the same filehandle, and have the same iomode. | type, correspond to the same filehandle, and have the same iomode. | |||
Layouts conflict when they overlap and differ in the content of the | Layouts conflict when they overlap and differ in the content of the | |||
layout (i.e., the storage device/file mapping parameters differ). | layout (i.e., the storage device/file mapping parameters differ). | |||
Note that differing iomodes do not lead to conflicting layouts. It | Note that differing iomodes do not lead to conflicting layouts. It | |||
is permissible for layouts with different iomodes, pertaining to the | is permissible for layouts with different iomodes, pertaining to the | |||
same byte-range, to be held by the same client. An example of this | same byte-range, to be held by the same client. An example of this | |||
would be copy-on-write functionality for a block/volume layout type. | would be copy-on-write functionality for a block/volume layout type. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section anchor="layout_iomode" numbered="true" toc="default"> | |||
<section title="Layout Iomode" anchor="layout_iomode"> | <name>Layout Iomode</name> | |||
<t> | <t> | |||
The layout iomode (data type layoutiomode4, see <xref | The layout iomode (data type layoutiomode4, see <xref target="layoutiomode4" f | |||
target="layoutiomode4" />) indicates to the metadata server the | ormat="default"/>) indicates to the metadata server the | |||
client's intent to perform either just READ operations | client's intent to perform either just READ operations | |||
or a mixture containing READ | or a mixture containing READ | |||
and WRITE operations. For certain layout | and WRITE operations. For certain layout | |||
types, it is useful for a client to specify this intent at the time it sends L AYOUTGET | types, it is useful for a client to specify this intent at the time it sends L AYOUTGET | |||
(<xref target="OP_LAYOUTGET" />). For example, for | (<xref target="OP_LAYOUTGET" format="default"/>). For example, for | |||
block/volume-based protocols, block allocation could occur when a | block/volume-based protocols, block allocation could occur when a | |||
LAYOUTIOMODE4_RW iomode is specified. A special LAYOUTIOMODE4_ANY iomode is d efined | LAYOUTIOMODE4_RW iomode is specified. A special LAYOUTIOMODE4_ANY iomode is d efined | |||
and can only be used for LAYOUTRETURN and CB_LAYOUTRECALL, not for | and can only be used for LAYOUTRETURN and CB_LAYOUTRECALL, not for | |||
LAYOUTGET. It specifies that layouts pertaining to both LAYOUTIOMODE4_READ an d | LAYOUTGET. It specifies that layouts pertaining to both LAYOUTIOMODE4_READ an d | |||
LAYOUTIOMODE4_RW iomodes are being returned or recalled, respectively. | LAYOUTIOMODE4_RW iomodes are being returned or recalled, respectively. | |||
</t> | </t> | |||
<t> | <t> | |||
A storage device may validate I/O with regard to the iomode; this | A storage device may validate I/O with regard to the iomode; this | |||
is dependent upon storage device implementation and layout type. | is dependent upon storage device implementation and layout type. | |||
Thus, if the client's layout iomode is inconsistent with the I/O | Thus, if the client's layout iomode is inconsistent with the I/O | |||
being performed, the storage device may reject the client's I/O with | being performed, the storage device may reject the client's I/O with | |||
an error indicating that a new layout with the correct iomode should be | an error indicating that a new layout with the correct iomode should be | |||
obtained via LAYOUTGET. For example, if a client gets a layout with a LAYOUTI OMODE4_READ iomode and | obtained via LAYOUTGET. For example, if a client gets a layout with a LAYOUTI OMODE4_READ iomode and | |||
performs a WRITE to a storage device, the storage device is allowed | performs a WRITE to a storage device, the storage device is allowed | |||
to reject that WRITE. | to reject that WRITE. | |||
</t> | </t> | |||
<t> | <t> | |||
The use of the layout iomode does not conflict with OPEN share modes or byte-r ange LOCK operations; | The use of the layout iomode does not conflict with OPEN share modes or byte-r ange LOCK operations; | |||
open share mode and byte-range lock conflicts are enforced as they are without the | open share mode and byte-range lock conflicts are enforced as they are without the | |||
use of pNFS and are logically separate from the pNFS layout level. | use of pNFS and are logically separate from the pNFS layout level. | |||
Open share modes and byte-range locks are the preferred method for | Open share modes and byte-range locks are the preferred method for | |||
restricting user access to data files. For example, an OPEN of | restricting user access to data files. For example, an OPEN of | |||
OPEN4_SHARE_ACCESS_WRITE does not conflict with a LAYOUTGET containing an iomo de | OPEN4_SHARE_ACCESS_WRITE does not conflict with a LAYOUTGET containing an iomo de | |||
of LAYOUTIOMODE4_RW performed by another client. Applications that depend | of LAYOUTIOMODE4_RW performed by another client. Applications that depend | |||
on writing into the same file concurrently may use byte-range locking to | on writing into the same file concurrently may use byte-range locking to | |||
serialize their accesses. | serialize their accesses. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="device_ids" numbered="true" toc="default"> | ||||
<section title="Device IDs" anchor="device_ids"> | <name>Device IDs</name> | |||
<t> | <t> | |||
The device ID (data type deviceid4, see | The device ID (data type deviceid4, see | |||
<xref target="deviceid4"/>) identifies a group of storage devices. The scope | <xref target="deviceid4" format="default"/>) identifies a group of storage d evices. The scope | |||
of a device ID is the pair <client ID, layout type>. In practice, a | of a device ID is the pair <client ID, layout type>. In practice, a | |||
significant amount of information may be required to fully address | significant amount of information may be required to fully address | |||
a storage device. Rather than embedding all such information in a | a storage device. Rather than embedding all such information in a | |||
layout, layouts embed device IDs. The NFSv4.1 operation | layout, layouts embed device IDs. The NFSv4.1 operation | |||
GETDEVICEINFO (<xref target="OP_GETDEVICEINFO" />) is used to | GETDEVICEINFO (<xref target="OP_GETDEVICEINFO" format="default"/>) is used t o | |||
retrieve the complete address information (including | retrieve the complete address information (including | |||
all device addresses for the device ID) regarding the storage | all device addresses for the device ID) regarding the storage | |||
device according to its layout type and device ID. For example, | device according to its layout type and device ID. For example, | |||
the address of an NFSv4.1 data server or of an object-based storage | the address of an NFSv4.1 data server or of an object-based storage | |||
device could be an IP address and port. The address of a block | device could be an IP address and port. The address of a block | |||
storage device could be a volume label. | storage device could be a volume label. | |||
</t> | </t> | |||
<t> | <t> | |||
Clients cannot expect the mapping between a device ID and | Clients cannot expect the mapping between a device ID and | |||
its storage device address(es) to persist across metadata server restart. | its storage device address(es) to persist across metadata server restart. | |||
See <xref target="mds_recovery" /> for a description of how | See <xref target="mds_recovery" format="default"/> for a description of how | |||
recovery works in that situation. | recovery works in that situation. | |||
</t> | </t> | |||
<t> | <t> | |||
A device ID lives as long as there is a layout | A device ID lives as long as there is a layout | |||
referring to the device ID. If there are no layouts | referring to the device ID. If there are no layouts | |||
referring to the device ID, the server is free to | referring to the device ID, the server is free to | |||
delete the device ID any time. | delete the device ID any time. | |||
Once a device ID is deleted by the server, the server MUST NOT | Once a device ID is deleted by the server, the server <bcp14>MUST NOT</bcp14 > | |||
reuse the device ID for the same layout type and client ID again. | reuse the device ID for the same layout type and client ID again. | |||
This requirement is feasible because the device ID is 16 bytes | This requirement is feasible because the device ID is 16 bytes | |||
long, leaving sufficient room to store a generation number if the | long, leaving sufficient room to store a generation number if the | |||
server's implementation requires most of the rest of the device ID's | server's implementation requires most of the rest of the device ID's | |||
content to be reused. This requirement is necessary because | content to be reused. This requirement is necessary because | |||
otherwise the race conditions between asynchronous notification | otherwise the race conditions between asynchronous notification | |||
of device ID addition and deletion would be too difficult to | of device ID addition and deletion would be too difficult to | |||
sort out. | sort out. | |||
</t> | </t> | |||
<t> | <t> | |||
Device ID to device address mappings are not leased, | Device ID to device address mappings are not leased, | |||
and can be changed at any time. (Note that while | and can be changed at any time. (Note that while | |||
device ID to device address mappings are likely | device ID to device address mappings are likely | |||
to change after the metadata server restarts, the | to change after the metadata server restarts, the | |||
server is not required to change the mappings.) | server is not required to change the mappings.) | |||
A server has two | A server has two | |||
choices for changing mappings. It can recall all | choices for changing mappings. It can recall all | |||
layouts referring to the device ID or it can use a | layouts referring to the device ID or it can use a | |||
notification mechanism. | notification mechanism. | |||
</t> | </t> | |||
<t> | <t> | |||
The NFSv4.1 protocol has no optimal way to recall | The NFSv4.1 protocol has no optimal way to recall | |||
all layouts that referred to a particular device ID | all layouts that referred to a particular device ID | |||
(unless the server associates a single device ID with | (unless the server associates a single device ID with | |||
a single fsid or a single client ID; in which case, | a single fsid or a single client ID; in which case, | |||
CB_LAYOUTRECALL has options for recalling all layouts | CB_LAYOUTRECALL has options for recalling all layouts | |||
associated with the fsid, client ID pair, or just the | associated with the fsid, client ID pair, or just the | |||
client ID). | client ID). | |||
</t> | </t> | |||
<t> | <t> | |||
Via a notification mechanism | Via a notification mechanism | |||
(see <xref target="OP_CB_NOTIFY_DEVICEID" />), | (see <xref target="OP_CB_NOTIFY_DEVICEID" format="default"/>), | |||
device ID to device address mappings can change over the duration | device ID to device address mappings can change over the duration | |||
of server operation without recalling or revoking the layouts that | of server operation without recalling or revoking the layouts that | |||
refer to device ID. The notification mechanism can also delete | refer to device ID. The notification mechanism can also delete | |||
a device ID, but only if the client has no layouts referring | a device ID, but only if the client has no layouts referring | |||
to the device ID. | to the device ID. | |||
A notification of a change to a device ID to device address | A notification of a change to a device ID to device address | |||
mapping will immediately or eventually invalidate some or all of | mapping will immediately or eventually invalidate some or all of | |||
the device ID's mappings. | the device ID's mappings. | |||
The server MUST support notifications and the client must | The server <bcp14>MUST</bcp14> support notifications and the client must | |||
request them before they can be used. For further information | request them before they can be used. For further information | |||
about the notification types <xref target="OP_CB_NOTIFY_DEVICEID" />. | about the notification types, see <xref target="OP_CB_NOTIFY_DEVICEID" forma | |||
t="default"/>. | ||||
</t> | ||||
</section> | ||||
</section> | ||||
<section title="pNFS Operations" anchor="pnfs_ops"> | </t> | |||
<t> | </section> | |||
</section> | ||||
<section anchor="pnfs_ops" numbered="true" toc="default"> | ||||
<name>pNFS Operations</name> | ||||
<t> | ||||
NFSv4.1 has several operations that are needed for | NFSv4.1 has several operations that are needed for | |||
pNFS servers, regardless of layout type or storage | pNFS servers, regardless of layout type or storage | |||
protocol. These operations are all sent to a metadata | protocol. These operations are all sent to a metadata | |||
server and summarized here. While pNFS is an OPTIONAL | server and summarized here. While pNFS is an <bcp14>OPTIONAL</bcp14> | |||
feature, if pNFS is implemented, some operations | feature, if pNFS is implemented, some operations | |||
are REQUIRED in order to comply with pNFS. See <xref | are <bcp14>REQUIRED</bcp14> in order to comply with pNFS. See <xref target="op | |||
target="operation_mandlist"/>. | eration_mandlist" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
These are the fore channel pNFS operations: | These are the fore channel pNFS operations: | |||
<list style='hanging'> | </t> | |||
<t hangText="GETDEVICEINFO"> | <dl newline="false" spacing="normal"> | |||
(<xref target="OP_GETDEVICEINFO" />), as noted previously | <dt>GETDEVICEINFO</dt> | |||
(<xref target="device_ids" />), returns the mapping of device ID to | <dd> | |||
(<xref target="OP_GETDEVICEINFO" format="default"/>), as noted previously | ||||
(<xref target="device_ids" format="default"/>), returns the mapping of device | ||||
ID to | ||||
storage device address. | storage device address. | |||
</t> | </dd> | |||
<dt>GETDEVICELIST</dt> | ||||
<t hangText="GETDEVICELIST"> | <dd> | |||
(<xref target="OP_GETDEVICELIST" />) | (<xref target="OP_GETDEVICELIST" format="default"/>) | |||
allows clients to fetch all device IDs | allows clients to fetch all device IDs | |||
for a specific file system. | for a specific file system. | |||
</t> | </dd> | |||
<t hangText="LAYOUTGET"> | <dt>LAYOUTGET</dt> | |||
(<xref target="OP_LAYOUTGET" />) is used by a client to get | <dd> | |||
(<xref target="OP_LAYOUTGET" format="default"/>) is used by a client to get | ||||
a layout for a file. | a layout for a file. | |||
</t> | </dd> | |||
<t hangText="LAYOUTCOMMIT"> | <dt>LAYOUTCOMMIT</dt> | |||
(<xref target="OP_LAYOUTCOMMIT" />) is used | <dd> | |||
(<xref target="OP_LAYOUTCOMMIT" format="default"/>) is used | ||||
to inform the metadata server of the client's intent to commit data | to inform the metadata server of the client's intent to commit data | |||
that has been written to the storage device (the storage device as | that has been written to the storage device (the storage device as | |||
originally indicated in the return value of LAYOUTGET). | originally indicated in the return value of LAYOUTGET). | |||
</t> | </dd> | |||
<t hangText="LAYOUTRETURN"> | <dt>LAYOUTRETURN</dt> | |||
(<xref target="OP_LAYOUTRETURN" />) is used | <dd> | |||
(<xref target="OP_LAYOUTRETURN" format="default"/>) is used | ||||
to return layouts for a file, a file system ID (FSID), or a client ID. | to return layouts for a file, a file system ID (FSID), or a client ID. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | <t> | |||
<t> | ||||
These are the backchannel pNFS operations: | These are the backchannel pNFS operations: | |||
<list style='hanging'> | </t> | |||
<t hangText="CB_LAYOUTRECALL"> | <dl newline="false" spacing="normal"> | |||
(<xref target="OP_CB_LAYOUTRECALL" />) recalls | <dt>CB_LAYOUTRECALL</dt> | |||
<dd> | ||||
(<xref target="OP_CB_LAYOUTRECALL" format="default"/>) recalls | ||||
a layout, all layouts belonging to a file system, or all | a layout, all layouts belonging to a file system, or all | |||
layouts belonging to a client ID. | layouts belonging to a client ID. | |||
</t> | </dd> | |||
<t hangText="CB_RECALL_ANY"> | <dt>CB_RECALL_ANY</dt> | |||
(<xref target="OP_CB_RECALL_ANY" />) | <dd> | |||
(<xref target="OP_CB_RECALL_ANY" format="default"/>) | ||||
tells a client that it needs to return some number of recallable | tells a client that it needs to return some number of recallable | |||
objects, including layouts, to the metadata server. | objects, including layouts, to the metadata server. | |||
</t> | </dd> | |||
<t hangText="CB_RECALLABLE_OBJ_AVAIL"> | <dt>CB_RECALLABLE_OBJ_AVAIL</dt> | |||
(<xref target="OP_CB_RECALLABLE_OBJ_AVAIL" />) tells a client | <dd> | |||
(<xref target="OP_CB_RECALLABLE_OBJ_AVAIL" format="default"/>) tells a client | ||||
that a recallable object that it was denied (in case of | that a recallable object that it was denied (in case of | |||
pNFS, a layout denied by LAYOUTGET) due to resource exhaustion | pNFS, a layout denied by LAYOUTGET) due to resource exhaustion | |||
is now available. | is now available. | |||
</t> | </dd> | |||
<t hangText="CB_NOTIFY_DEVICEID"> | <dt>CB_NOTIFY_DEVICEID</dt> | |||
(<xref target="OP_CB_NOTIFY_DEVICEID" />) notifies the client of | <dd> | |||
(<xref target="OP_CB_NOTIFY_DEVICEID" format="default"/>) notifies the client | ||||
of | ||||
changes to device IDs. | changes to device IDs. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | </section> | |||
<section anchor="pnfs_attr" numbered="true" toc="default"> | ||||
</section> | <name>pNFS Attributes</name> | |||
<section title="pNFS Attributes" anchor="pnfs_attr"> | <t> | |||
<t> | ||||
A number of attributes specific to pNFS are listed and described in | A number of attributes specific to pNFS are listed and described in | |||
<xref target="pnfs_attr_full" />. | <xref target="pnfs_attr_full" format="default"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="Layout Semantics"> | <name>Layout Semantics</name> | |||
<section anchor="layout_semantics" numbered="true" toc="default"> | ||||
<section title="Guarantees Provided by Layouts" anchor="layout_semantics"> | <name>Guarantees Provided by Layouts</name> | |||
<t> | <t> | |||
Layouts grant to the client the ability to access data located at | Layouts grant to the client the ability to access data located at | |||
a storage device with the appropriate storage protocol. The client | a storage device with the appropriate storage protocol. The client | |||
is guaranteed the layout will be recalled when one of two things | is guaranteed the layout will be recalled when one of two things | |||
occur: either a conflicting layout is requested or the state | occur: either a conflicting layout is requested or the state | |||
encapsulated by the layout becomes invalid (this can happen when | encapsulated by the layout becomes invalid (this can happen when | |||
an event directly or indirectly modifies the layout). When a layout | an event directly or indirectly modifies the layout). When a layout | |||
is recalled and returned by the client, the client continues with | is recalled and returned by the client, the client continues with | |||
the ability to access file data with normal NFSv4.1 operations | the ability to access file data with normal NFSv4.1 operations | |||
through the metadata server. Only the ability to access the storage | through the metadata server. Only the ability to access the storage | |||
devices is affected. | devices is affected. | |||
</t> | </t> | |||
<t> | <t> | |||
The requirement of NFSv4.1 that all user access rights MUST be | The requirement of NFSv4.1 that all user access rights <bcp14>MUST</bcp14> be | |||
obtained through the appropriate OPEN, LOCK, and ACCESS operations | obtained through the appropriate OPEN, LOCK, and ACCESS operations | |||
is not modified with the existence of layouts. Layouts are provided | is not modified with the existence of layouts. Layouts are provided | |||
to NFSv4.1 clients, and user access still follows the rules of the | to NFSv4.1 clients, and user access still follows the rules of the | |||
protocol as if they did not exist. It is a requirement that for a | protocol as if they did not exist. It is a requirement that for a | |||
client to access a storage device, a layout must be held by the | client to access a storage device, a layout must be held by the | |||
client. If a storage device receives an I/O request for a byte-range for | client. If a storage device receives an I/O request for a byte-range for | |||
which the client does not hold a layout, the storage device SHOULD | which the client does not hold a layout, the storage device <bcp14>SHOULD</bcp 14> | |||
reject that I/O request. Note that the act of modifying a file for | reject that I/O request. Note that the act of modifying a file for | |||
which a layout is held does not necessarily conflict with the | which a layout is held does not necessarily conflict with the | |||
holding of the layout that describes the file being modified. | holding of the layout that describes the file being modified. | |||
Therefore, it is the requirement of the storage protocol or layout | Therefore, it is the requirement of the storage protocol or layout | |||
type that determines the necessary behavior. For example, | type that determines the necessary behavior. For example, | |||
block/volume layout types require that the layout's | block/volume layout types require that the layout's | |||
iomode agree with the type of I/O being performed. | iomode agree with the type of I/O being performed. | |||
</t> | </t> | |||
<t> | <t> | |||
Depending upon the layout type and storage protocol in use, storage | Depending upon the layout type and storage protocol in use, storage | |||
device access permissions may be granted by LAYOUTGET and may be | device access permissions may be granted by LAYOUTGET and may be | |||
encoded within the type-specific layout. For an example of storage | encoded within the type-specific layout. For an example of storage | |||
device access permissions, see an object-based protocol such as <xref | device access permissions, see an object-based protocol such as <xref target=" | |||
target="OSD-T10" />. If access permissions are encoded within the | OSD-T10" format="default"/>. If access permissions are encoded within the | |||
layout, the metadata server SHOULD recall the layout when those | layout, the metadata server <bcp14>SHOULD</bcp14> recall the layout when those | |||
permissions become invalid for any reason -- for example, when a file | permissions become invalid for any reason -- for example, when a file | |||
becomes unwritable or inaccessible to a client. Note, clients are | becomes unwritable or inaccessible to a client. Note, clients are | |||
still required to perform the appropriate | still required to perform the appropriate | |||
OPEN, LOCK, and ACCESS operations as described above. The degree to which it is | OPEN, LOCK, and ACCESS operations as described above. The degree to which it is | |||
possible for the client to circumvent these operations and | possible for the client to circumvent these operations and | |||
the consequences of doing so must be clearly specified by the | the consequences of doing so must be clearly specified by the | |||
individual layout type specifications. In addition, these | individual layout type specifications. In addition, these | |||
specifications must be clear about the requirements and | specifications must be clear about the requirements and | |||
non-requirements for the checking performed by the server. | non-requirements for the checking performed by the server. | |||
</t> | </t> | |||
<t> | <t> | |||
In the presence of pNFS functionality, mandatory byte-range locks MUST | In the presence of pNFS functionality, mandatory byte-range locks <bcp14>MUST< | |||
/bcp14> | ||||
behave as they would without pNFS. Therefore, if mandatory file | behave as they would without pNFS. Therefore, if mandatory file | |||
locks and layouts are provided simultaneously, the storage device | locks and layouts are provided simultaneously, the storage device | |||
MUST be able to enforce the mandatory byte-range locks. For example, if | <bcp14>MUST</bcp14> be able to enforce the mandatory byte-range locks. For ex ample, if | |||
one client obtains a mandatory byte-range lock and a second client accesses th e | one client obtains a mandatory byte-range lock and a second client accesses th e | |||
storage device, the storage device MUST appropriately restrict I/O | storage device, the storage device <bcp14>MUST</bcp14> appropriately restrict I/O | |||
for the range of the mandatory byte-range lock. If the storage | for the range of the mandatory byte-range lock. If the storage | |||
device is incapable of providing this check in the presence of | device is incapable of providing this check in the presence of | |||
mandatory byte-range locks, then the metadata server MUST NOT grant | mandatory byte-range locks, then the metadata server <bcp14>MUST NOT</bcp14> g rant | |||
layouts and mandatory byte-range locks simultaneously. | layouts and mandatory byte-range locks simultaneously. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="obtaining_layout" numbered="true" toc="default"> | ||||
<section title="Getting a Layout" anchor="obtaining_layout"> | <name>Getting a Layout</name> | |||
<t> | <t> | |||
A client obtains a layout with the | A client obtains a layout with the | |||
LAYOUTGET operation. The metadata server | LAYOUTGET operation. The metadata server | |||
will grant layouts of a particular type | will grant layouts of a particular type | |||
(e.g., block/volume, object, or file). | (e.g., block/volume, object, or file). | |||
The client selects an appropriate layout | The client selects an appropriate layout | |||
type that the server supports and the client | type that the server supports and the client | |||
is prepared to use. The layout returned to | is prepared to use. The layout returned to | |||
the client might not exactly match the | the client might not exactly match the | |||
requested byte-range as described in <xref | requested byte-range as described in <xref target="OP_LAYOUTGET_DESCRIPTION" f | |||
target="OP_LAYOUTGET_DESCRIPTION"/>. As needed a client | ormat="default"/>. As needed a client | |||
may send multiple LAYOUTGET operations; these might result | may send multiple LAYOUTGET operations; these might result | |||
in multiple overlapping, non-conflicting layouts (see | in multiple overlapping, non-conflicting layouts (see | |||
<xref target="layout"/>). | <xref target="layout" format="default"/>). | |||
</t> | </t> | |||
<t> | <t> | |||
In order to get a layout, the client must first have opened the file | In order to get a layout, the client must first have opened the file | |||
via the OPEN operation. When a client has no layout on a file, it | via the OPEN operation. When a client has no layout on a file, it | |||
MUST present an open stateid, a delegation stateid, or | <bcp14>MUST</bcp14> present an open stateid, a delegation stateid, or | |||
a byte-range lock stateid in the loga_stateid argument. A successful | a byte-range lock stateid in the loga_stateid argument. A successful | |||
LAYOUTGET result includes a layout stateid. The first successful | LAYOUTGET result includes a layout stateid. The first successful | |||
LAYOUTGET processed by the server using a non-layout stateid as an | LAYOUTGET processed by the server using a non-layout stateid as an | |||
argument MUST have the "seqid" field of the layout stateid in the | argument <bcp14>MUST</bcp14> have the "seqid" field of the layout stateid in t | |||
response set to one. Thereafter, the client MUST use a layout | he | |||
stateid (see <xref target="layout_stateid" />) on future invocations | response set to one. Thereafter, the client <bcp14>MUST</bcp14> use a layout | |||
of LAYOUTGET on the file, and the "seqid" MUST NOT be set to | stateid (see <xref target="layout_stateid" format="default"/>) on future invoc | |||
ations | ||||
of LAYOUTGET on the file, and the "seqid" <bcp14>MUST NOT</bcp14> be set to | ||||
zero. Once the layout has been retrieved, it can be held across | zero. Once the layout has been retrieved, it can be held across | |||
multiple OPEN and CLOSE sequences. Therefore, a client may hold a | multiple OPEN and CLOSE sequences. Therefore, a client may hold a | |||
layout for a file that is not currently open by any user on the | layout for a file that is not currently open by any user on the | |||
client. This allows for the caching of layouts beyond CLOSE. | client. This allows for the caching of layouts beyond CLOSE. | |||
</t> | </t> | |||
<t> | <t> | |||
The storage protocol used by the client to access the data on the | The storage protocol used by the client to access the data on the | |||
storage device is determined by the layout's type. The client is | storage device is determined by the layout's type. The client is | |||
responsible for matching the layout type with an available method to | responsible for matching the layout type with an available method to | |||
interpret and use the layout. The method for this layout type | interpret and use the layout. The method for this layout type | |||
selection is outside the scope of the pNFS functionality. | selection is outside the scope of the pNFS functionality. | |||
</t> | </t> | |||
<t> | <t> | |||
Although the metadata server is in control | Although the metadata server is in control | |||
of the layout for a file, the pNFS client | of the layout for a file, the pNFS client | |||
can provide hints to the server when a file | can provide hints to the server when a file | |||
is opened or created about the preferred | is opened or created about the preferred | |||
layout type and aggregation schemes. | layout type and aggregation schemes. | |||
pNFS introduces a layout_hint attribute (<xref | pNFS introduces a layout_hint attribute (<xref target="attrdef_layout_hint" fo | |||
target="attrdef_layout_hint" />) | rmat="default"/>) | |||
that the client can set at file creation | that the client can set at file creation | |||
time to provide a hint to the server for new | time to provide a hint to the server for new | |||
files. Setting this attribute separately, | files. Setting this attribute separately, | |||
after the file has been created might make | after the file has been created might make | |||
it difficult, or impossible, for the server | it difficult, or impossible, for the server | |||
implementation to comply. | implementation to comply. | |||
</t> | </t> | |||
<t> | <t> | |||
Because the EXCLUSIVE4 createmode4 does not allow the | Because the EXCLUSIVE4 createmode4 does not allow the | |||
setting of attributes at file creation time, NFSv4.1 | setting of attributes at file creation time, NFSv4.1 | |||
introduces the EXCLUSIVE4_1 createmode4, which does | introduces the EXCLUSIVE4_1 createmode4, which does | |||
allow attributes to be set at file creation time. In | allow attributes to be set at file creation time. In | |||
addition, if the session is created with persistent | addition, if the session is created with persistent | |||
reply caches, EXCLUSIVE4_1 is neither necessary | reply caches, EXCLUSIVE4_1 is neither necessary | |||
nor allowed. Instead, GUARDED4 both works better and is | nor allowed. Instead, GUARDED4 both works better and is | |||
prescribed. <xref target="exclusive_create" /> in <xref | prescribed. <xref target="exclusive_create" format="default"/> in <xref target | |||
target="OP_OPEN_DESCRIPTION" /> summarizes how a client | ="OP_OPEN_DESCRIPTION" format="default"/> summarizes how a client | |||
is allowed to send an exclusive create. | is allowed to send an exclusive create. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="layout_stateid" numbered="true" toc="default"> | ||||
<section title="Layout Stateid" anchor="layout_stateid"> | <name>Layout Stateid</name> | |||
<t> | <t> | |||
As with all other stateids, the layout stateid consists of a "seqid" and | As with all other stateids, the layout stateid consists of a "seqid" and | |||
"other" field. Once a layout stateid is established, the "other" field | "other" field. Once a layout stateid is established, the "other" field | |||
will stay constant unless the stateid is revoked or the client | will stay constant unless the stateid is revoked or the client | |||
returns all layouts on the file and the server disposes of the | returns all layouts on the file and the server disposes of the | |||
stateid. The "seqid" field is initially set to one, and is never | stateid. The "seqid" field is initially set to one, and is never | |||
zero on any NFSv4.1 operation that uses layout stateids, whether it | zero on any NFSv4.1 operation that uses layout stateids, whether it | |||
is a fore channel or backchannel operation. After the layout stateid | is a fore channel or backchannel operation. After the layout stateid | |||
is established, the server increments by one the value of the | is established, the server increments by one the value of the | |||
"seqid" in each subsequent LAYOUTGET and LAYOUTRETURN response, and | "seqid" in each subsequent LAYOUTGET and LAYOUTRETURN response, and | |||
in each CB_LAYOUTRECALL request. | in each CB_LAYOUTRECALL request. | |||
</t> | </t> | |||
<t> | <t> | |||
Given the design goal of pNFS to provide parallelism, the layout | Given the design goal of pNFS to provide parallelism, the layout | |||
stateid differs from other stateid types in that the client is | stateid differs from other stateid types in that the client is | |||
expected to send LAYOUTGET and LAYOUTRETURN operations in parallel. | expected to send LAYOUTGET and LAYOUTRETURN operations in parallel. | |||
The "seqid" value is used by the client to properly sort responses | The "seqid" value is used by the client to properly sort responses | |||
to LAYOUTGET and LAYOUTRETURN. The "seqid" is also used to prevent | to LAYOUTGET and LAYOUTRETURN. The "seqid" is also used to prevent | |||
race conditions between LAYOUTGET and CB_LAYOUTRECALL. Given that the | race conditions between LAYOUTGET and CB_LAYOUTRECALL. Given that the | |||
processing rules differ from layout stateids and other stateid | processing rules differ from layout stateids and other stateid | |||
types, only the pNFS sections of this document should be considered | types, only the pNFS sections of this document should be considered | |||
to determine proper layout stateid handling. | to determine proper layout stateid handling. | |||
</t> | </t> | |||
<t> | <t> | |||
Once the client receives a layout stateid, it MUST use the correct | Once the client receives a layout stateid, it <bcp14>MUST</bcp14> use the corr | |||
ect | ||||
"seqid" for subsequent LAYOUTGET or LAYOUTRETURN operations. The | "seqid" for subsequent LAYOUTGET or LAYOUTRETURN operations. The | |||
correct "seqid" is defined as the highest "seqid" value from | correct "seqid" is defined as the highest "seqid" value from | |||
responses of fully processed LAYOUTGET or LAYOUTRETURN operations or | responses of fully processed LAYOUTGET or LAYOUTRETURN operations or | |||
arguments of a fully processed CB_LAYOUTRECALL operation. Since the | arguments of a fully processed CB_LAYOUTRECALL operation. Since the | |||
server is incrementing the "seqid" value on each layout operation, | server is incrementing the "seqid" value on each layout operation, | |||
the client may determine the order of operation processing by | the client may determine the order of operation processing by | |||
inspecting the "seqid" value. In the case of overlapping layout | inspecting the "seqid" value. In the case of overlapping layout | |||
ranges, the ordering information will provide the client the | ranges, the ordering information will provide the client the | |||
knowledge of which layout ranges are held. Note that overlapping | knowledge of which layout ranges are held. Note that overlapping | |||
layout ranges may occur because of the client's specific requests or | layout ranges may occur because of the client's specific requests or | |||
because the server is allowed to expand the range of a requested | because the server is allowed to expand the range of a requested | |||
layout and notify the client in the LAYOUTRETURN results. Additional | layout and notify the client in the LAYOUTRETURN results. Additional | |||
layout stateid sequencing requirements are provided in | layout stateid sequencing requirements are provided in | |||
<xref target="pnfs_operation_sequencing"/>. | <xref target="pnfs_operation_sequencing" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
The client's receipt of a "seqid" is not sufficient for subsequent | The client's receipt of a "seqid" is not sufficient for subsequent | |||
use. The client must fully process the operations before the | use. The client must fully process the operations before the | |||
"seqid" can be used. For LAYOUTGET results, if | "seqid" can be used. For LAYOUTGET results, if | |||
the client is not using the forgetful model | the client is not using the forgetful model | |||
(<xref target="recall_robustness"/>), it MUST first update its | (<xref target="recall_robustness" format="default"/>), it <bcp14>MUST</bcp14> first update its | |||
record of what ranges of the file's layout it has before using the | record of what ranges of the file's layout it has before using the | |||
seqid. For LAYOUTRETURN results, the client MUST delete the range | seqid. For LAYOUTRETURN results, the client <bcp14>MUST</bcp14> delete the ran ge | |||
from its record of what ranges of the file's layout it had before | from its record of what ranges of the file's layout it had before | |||
using the seqid. For CB_LAYOUTRECALL arguments, the client MUST send | using the seqid. For CB_LAYOUTRECALL arguments, the client <bcp14>MUST</bcp14> send | |||
a response to the recall before using the seqid. | a response to the recall before using the seqid. | |||
The fundamental requirement in client | The fundamental requirement in client | |||
processing is that the "seqid" is used to provide the order of | processing is that the "seqid" is used to provide the order of | |||
processing. LAYOUTGET results may be processed in parallel. | processing. LAYOUTGET results may be processed in parallel. | |||
LAYOUTRETURN results may be processed in parallel. LAYOUTGET and | LAYOUTRETURN results may be processed in parallel. LAYOUTGET and | |||
LAYOUTRETURN responses may be processed in parallel as long as the | LAYOUTRETURN responses may be processed in parallel as long as the | |||
ranges do not overlap. CB_LAYOUTRECALL request processing MUST be | ranges do not overlap. CB_LAYOUTRECALL request processing <bcp14>MUST</bcp14> be | |||
processed in "seqid" order at all times. | processed in "seqid" order at all times. | |||
</t> | </t> | |||
<t> | <t> | |||
Once a client has no more layouts on a file, the layout stateid is | Once a client has no more layouts on a file, the layout stateid is | |||
no longer valid and MUST NOT be used. Any attempt to use such a | no longer valid and <bcp14>MUST NOT</bcp14> be used. Any attempt to use such a | |||
layout stateid will result in NFS4ERR_BAD_STATEID. | layout stateid will result in NFS4ERR_BAD_STATEID. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section anchor="committing_layout" numbered="true" toc="default"> | |||
<name>Committing a Layout</name> | ||||
<section title="Committing a Layout" anchor="committing_layout"> | <t> | |||
<t> | ||||
Allowing for varying storage protocol capabilities, the pNFS | Allowing for varying storage protocol capabilities, the pNFS | |||
protocol does not require the metadata server and storage devices to | protocol does not require the metadata server and storage devices to | |||
have a consistent view of file attributes and data location | have a consistent view of file attributes and data location | |||
mappings. Data location mapping refers to aspects such as which offsets | mappings. Data location mapping refers to aspects such as which offsets | |||
store data as opposed to storing holes (see <xref | store data as opposed to storing holes (see <xref target="sparse_dense" format | |||
target="sparse_dense" /> for a discussion). Related issues arise | ="default"/> for a discussion). Related issues arise | |||
for storage protocols where a layout may hold provisionally | for storage protocols where a layout may hold provisionally | |||
allocated blocks where the allocation of those blocks does not | allocated blocks where the allocation of those blocks does not | |||
survive a complete restart of both the client and server. Because | survive a complete restart of both the client and server. Because | |||
of this inconsistency, it is necessary to resynchronize the client | of this inconsistency, it is necessary to resynchronize the client | |||
with the metadata server and its storage devices and make any | with the metadata server and its storage devices and make any | |||
potential changes available to other clients. This is accomplished | potential changes available to other clients. This is accomplished | |||
by use of the LAYOUTCOMMIT operation. | by use of the LAYOUTCOMMIT operation. | |||
</t> | </t> | |||
<t> | <t> | |||
The LAYOUTCOMMIT operation is responsible for committing a modified | The LAYOUTCOMMIT operation is responsible for committing a modified | |||
layout to the metadata server. The data should be written | layout to the metadata server. The data should be written | |||
and committed to the appropriate storage devices before the | and committed to the appropriate storage devices before the | |||
LAYOUTCOMMIT occurs. The | LAYOUTCOMMIT occurs. The | |||
scope of the LAYOUTCOMMIT operation depends on the storage protocol | scope of the LAYOUTCOMMIT operation depends on the storage protocol | |||
in use. It is important to note that the level of | in use. It is important to note that the level of | |||
synchronization is from the point of view of the client that sent | synchronization is from the point of view of the client that sent | |||
the LAYOUTCOMMIT. The updated state on the metadata server need | the LAYOUTCOMMIT. The updated state on the metadata server need | |||
only reflect the state as of the client's last operation previous to | only reflect the state as of the client's last operation previous to | |||
the LAYOUTCOMMIT. The metadata server is not REQUIRED to maintain a global vi ew | the LAYOUTCOMMIT. The metadata server is not <bcp14>REQUIRED</bcp14> to maint ain a global view | |||
that accounts for other clients' I/O that may have occurred within | that accounts for other clients' I/O that may have occurred within | |||
the same time frame. | the same time frame. | |||
</t> | </t> | |||
<t> | <t> | |||
For block/volume-based layouts, LAYOUTCOMMIT may require | For block/volume-based layouts, LAYOUTCOMMIT may require | |||
updating the block list that comprises the file and committing this | updating the block list that comprises the file and committing this | |||
layout to stable storage. For file-based layouts, synchronization of | layout to stable storage. For file-based layouts, synchronization of | |||
attributes between the metadata and storage devices, primarily the | attributes between the metadata and storage devices, primarily the | |||
size attribute, is required. | size attribute, is required. | |||
</t> | </t> | |||
<t> | <t> | |||
The control protocol is free to synchronize the attributes before | The control protocol is free to synchronize the attributes before | |||
it receives a LAYOUTCOMMIT; however, upon successful completion of a | it receives a LAYOUTCOMMIT; however, upon successful completion of a | |||
LAYOUTCOMMIT, state that exists on the metadata server that | LAYOUTCOMMIT, state that exists on the metadata server that | |||
describes the file MUST be synchronized with the state that exists on the | describes the file <bcp14>MUST</bcp14> be synchronized with the state that exi sts on the | |||
storage devices that comprise that file as of the client's | storage devices that comprise that file as of the client's | |||
last sent operation. Thus, a client that queries the size of a file | last sent operation. Thus, a client that queries the size of a file | |||
between a WRITE to a storage device and the LAYOUTCOMMIT might observe | between a WRITE to a storage device and the LAYOUTCOMMIT might observe | |||
a size that does not reflect the actual data written. | a size that does not reflect the actual data written. | |||
</t> | </t> | |||
<t> | ||||
<t> | The client <bcp14>MUST</bcp14> have a layout in order to send a LAYOUTCOMMIT o | |||
The client MUST have a layout in order to send a LAYOUTCOMMIT operation. | peration. | |||
</t> | </t> | |||
<section numbered="true" toc="default"> | ||||
<section title="LAYOUTCOMMIT and change/time_modify"> | <name>LAYOUTCOMMIT and change/time_modify</name> | |||
<t> | <t> | |||
The change and time_modify attributes may be updated | The change and time_modify attributes may be updated | |||
by the server when the LAYOUTCOMMIT operation is processed. The | by the server when the LAYOUTCOMMIT operation is processed. The | |||
reason for this is that some layout types do not support the update | reason for this is that some layout types do not support the update | |||
of these attributes when the storage devices process I/O operations. | of these attributes when the storage devices process I/O operations. | |||
If a client has a layout with the LAYOUTIOMODE4_RW iomode on the file, | If a client has a layout with the LAYOUTIOMODE4_RW iomode on the file, | |||
the client MAY provide a suggested value to the server for | the client <bcp14>MAY</bcp14> provide a suggested value to the server for | |||
time_modify within the arguments to LAYOUTCOMMIT. | time_modify within the arguments to LAYOUTCOMMIT. | |||
Based on the layout type, the provided value may or may not be used. | Based on the layout type, the provided value may or may not be used. | |||
The server should sanity-check the client-provided values | The server should sanity-check the client-provided values | |||
before they are used. For example, the server should ensure that | before they are used. For example, the server should ensure that | |||
time does not flow backwards. The client always has the option to | time does not flow backwards. The client always has the option to | |||
set time_modify through an explicit SETATTR operation. | set time_modify through an explicit SETATTR operation. | |||
</t> | </t> | |||
<t> | <t> | |||
For some layout protocols, the storage device is able to notify the | For some layout protocols, the storage device is able to notify the | |||
metadata server of the occurrence of an I/O; as a result, the | metadata server of the occurrence of an I/O; as a result, the | |||
change and time_modify attributes may be updated at | change and time_modify attributes may be updated at | |||
the metadata server. For a metadata server that is capable of | the metadata server. For a metadata server that is capable of | |||
monitoring updates to the change and time_modify | monitoring updates to the change and time_modify | |||
attributes, LAYOUTCOMMIT processing is not required to update the | attributes, LAYOUTCOMMIT processing is not required to update the | |||
change attribute. In this case, the metadata server must ensure that | change attribute. In this case, the metadata server must ensure that | |||
no further update to the data has occurred since the last update of | no further update to the data has occurred since the last update of | |||
the attributes; file-based protocols may have enough information to | the attributes; file-based protocols may have enough information to | |||
make this determination or may update the change attribute upon each | make this determination or may update the change attribute upon each | |||
file modification. This also applies for the time_modify | file modification. This also applies for the time_modify | |||
attribute. If the server implementation is able to | attribute. If the server implementation is able to | |||
determine that the file has not been modified since the last | determine that the file has not been modified since the last | |||
time_modify update, the server need not update time_modify at | time_modify update, the server need not update time_modify at | |||
LAYOUTCOMMIT. At LAYOUTCOMMIT completion, the updated attributes | LAYOUTCOMMIT. At LAYOUTCOMMIT completion, the updated attributes | |||
should be visible if that file was modified since the latest | should be visible if that file was modified since the latest | |||
previous LAYOUTCOMMIT or LAYOUTGET. | previous LAYOUTCOMMIT or LAYOUTGET. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="LAYOUTCOMMIT and size" anchor="general_layoutcommit"> | <section anchor="general_layoutcommit" numbered="true" toc="default"> | |||
<t> | <name>LAYOUTCOMMIT and size</name> | |||
<t> | ||||
The size of a file may be updated when the LAYOUTCOMMIT operation is | The size of a file may be updated when the LAYOUTCOMMIT operation is | |||
used by the client. One of the fields in the argument to | used by the client. One of the fields in the argument to | |||
LAYOUTCOMMIT is loca_last_write_offset; this field indicates the | LAYOUTCOMMIT is loca_last_write_offset; this field indicates the | |||
highest byte offset written but not yet committed with the | highest byte offset written but not yet committed with the | |||
LAYOUTCOMMIT operation. The data type of loca_last_write_offset is | LAYOUTCOMMIT operation. The data type of loca_last_write_offset is | |||
newoffset4 and is switched on a boolean value, no_newoffset, that | newoffset4 and is switched on a boolean value, no_newoffset, that | |||
indicates if a previous write occurred or not. If no_newoffset is | indicates if a previous write occurred or not. If no_newoffset is | |||
FALSE, an offset is not given. If the client has a layout with | FALSE, an offset is not given. If the client has a layout with | |||
LAYOUTIOMODE4_RW iomode on the file, with a byte-range (denoted by the values of lo_offset and lo_length) | LAYOUTIOMODE4_RW iomode on the file, with a byte-range (denoted by the values of lo_offset and lo_length) | |||
that overlaps loca_last_write_offset, then the client MAY | that overlaps loca_last_write_offset, then the client <bcp14>MAY</bcp14> | |||
set no_newoffset to TRUE and provide an offset that will | set no_newoffset to TRUE and provide an offset that will | |||
update the file size. Keep in mind that offset is not the same | update the file size. Keep in mind that offset is not the same | |||
as length, though they are related. For example, a loca_last_write_offset | as length, though they are related. For example, a loca_last_write_offset | |||
value of zero means that one byte was written at offset zero, and so | value of zero means that one byte was written at offset zero, and so | |||
the length of the file is at least one byte. | the length of the file is at least one byte. | |||
</t> | </t> | |||
<t> | <t> | |||
The metadata server may do one of the following: | The metadata server may do one of the following: | |||
<list style="numbers"> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
Update the file's size using the last write offset provided by | Update the file's size using the last write offset provided by | |||
the client as either the true file size or as a hint of the file | the client as either the true file size or as a hint of the file | |||
size. If the metadata server has a method available, any new | size. If the metadata server has a method available, any new | |||
value for file size should be sanity-checked. For example, the | value for file size should be sanity-checked. For example, the | |||
file must not be truncated if the client presents a last write | file must not be truncated if the client presents a last write | |||
offset less than the file's current size. | offset less than the file's current size. | |||
</t> | </li> | |||
<t> | <li> | |||
Ignore the client-provided last write offset; the metadata | Ignore the client-provided last write offset; the metadata | |||
server must have sufficient knowledge from other sources to | server must have sufficient knowledge from other sources to | |||
determine the file's size. For example, the metadata server | determine the file's size. For example, the metadata server | |||
queries the storage devices with the control protocol. | queries the storage devices with the control protocol. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | <t> | |||
<t> | ||||
The method chosen to update the file's size will depend on the | The method chosen to update the file's size will depend on the | |||
storage device's and/or the control protocol's capabilities. For | storage device's and/or the control protocol's capabilities. For | |||
example, if the storage devices are block devices with no knowledge | example, if the storage devices are block devices with no knowledge | |||
of file size, the metadata server must rely on the client to set the | of file size, the metadata server must rely on the client to set the | |||
last write offset appropriately. | last write offset appropriately. | |||
</t> | </t> | |||
<t> | <t> | |||
The results of LAYOUTCOMMIT contain a new size value in the form of | The results of LAYOUTCOMMIT contain a new size value in the form of | |||
a newsize4 union data type. If the file's size is set as a result | a newsize4 union data type. If the file's size is set as a result | |||
of LAYOUTCOMMIT, the metadata server must reply with the new size; | of LAYOUTCOMMIT, the metadata server must reply with the new size; | |||
otherwise, the new size is not provided. | otherwise, the new size is not provided. | |||
If the file size is updated, the metadata server SHOULD update the | If the file size is updated, the metadata server <bcp14>SHOULD</bcp14> update the | |||
storage devices such that the new file size is reflected when | storage devices such that the new file size is reflected when | |||
LAYOUTCOMMIT processing is complete. For example, the client should | LAYOUTCOMMIT processing is complete. For example, the client should | |||
be able to read up to the new file size. | be able to read up to the new file size. | |||
</t> | </t> | |||
<t> | <t> | |||
The client can extend the length of a file | The client can extend the length of a file | |||
or truncate a file by sending a SETATTR operation to the metadata server | or truncate a file by sending a SETATTR operation to the metadata server | |||
with the size attribute specified. If the size specified is larger than | with the size attribute specified. If the size specified is larger than | |||
the current size of the file, the file is "zero extended", i.e., zeros are | the current size of the file, the file is "zero extended", i.e., zeros are | |||
implicitly added between the file's previous EOF and the new EOF. | implicitly added between the file's previous EOF and the new EOF. | |||
(In many implementations, the zero-extended byte-range | (In many implementations, the zero-extended byte-range | |||
of the file consists of unallocated | of the file consists of unallocated | |||
holes in the file.) When the client writes past EOF via WRITE, | holes in the file.) When the client writes past EOF via WRITE, | |||
the SETATTR operation does not need to be used. | the SETATTR operation does not need to be used. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="LAYOUTCOMMIT and layoutupdate" anchor="layoutcommit_update"> | <section anchor="layoutcommit_update" numbered="true" toc="default"> | |||
<t> | <name>LAYOUTCOMMIT and layoutupdate</name> | |||
The LAYOUTCOMMIT argument contains a loca_layoutupdate field (<xref | <t> | |||
target="OP_LAYOUTCOMMIT_ARGUMENT"/>) of data type layoutupdate4 | The LAYOUTCOMMIT argument contains a loca_layoutupdate field (<xref target="OP | |||
(<xref target="layoutupdate4"/>). This argument is a | _LAYOUTCOMMIT_ARGUMENT" format="default"/>) of data type layoutupdate4 | |||
(<xref target="layoutupdate4" format="default"/>). This argument is a | ||||
layout-type-specific structure. The structure can be used to pass | layout-type-specific structure. The structure can be used to pass | |||
arbitrary layout-type-specific information from the client to the | arbitrary layout-type-specific information from the client to the | |||
metadata server at LAYOUTCOMMIT time. For example, if using a | metadata server at LAYOUTCOMMIT time. For example, if using a | |||
block/volume layout, the client can indicate to the metadata server | block/volume layout, the client can indicate to the metadata server | |||
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 | same layout-type-specific content returned by LAYOUTGET (<xref target="OP_LAYO | |||
target="OP_LAYOUTGET_RESULT" />) in the loc_body field of the | UTGET_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> <!-- Layout Semantics --> | </section> | |||
<section title="Recalling a Layout" anchor="recalling_layout"> | <section anchor="recalling_layout" numbered="true" toc="default"> | |||
<t> | <name>Recalling a Layout</name> | |||
<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 | |||
changes the layout will result in a recall of the layout. A layout | changes the layout will result in a recall of the layout. A layout | |||
is recalled by the CB_LAYOUTRECALL callback operation (see <xref | is recalled by the CB_LAYOUTRECALL callback operation (see <xref target="OP_CB | |||
target="OP_CB_LAYOUTRECALL" />) and returned with LAYOUTRETURN (see <xref | _LAYOUTRECALL" format="default"/>) and returned with LAYOUTRETURN (see <xref tar | |||
target="OP_LAYOUTRETURN" />). The CB_LAYOUTRECALL operation may | get="OP_LAYOUTRETURN" format="default"/>). The CB_LAYOUTRECALL operation may | |||
recall a layout identified by a byte-range, all layouts | recall a layout identified by a byte-range, all layouts | |||
associated with a file system ID (FSID), or all layouts associated with | associated with a file system ID (FSID), or all layouts associated with | |||
a client ID. | a client ID. | |||
<xref target="pnfs_operation_sequencing" /> discusses sequencing issues | <xref target="pnfs_operation_sequencing" format="default"/> discusses sequenci ng issues | |||
surrounding the getting, returning, and recalling of layouts. | surrounding the getting, returning, and recalling of layouts. | |||
</t> | </t> | |||
<t> | <t> | |||
An iomode is also specified when recalling a layout. | An iomode is also specified when recalling a layout. | |||
Generally, the iomode in the recall request must match the layout | Generally, the iomode in the recall request must match the layout | |||
being returned; for example, a recall with an iomode of | being returned; for example, a recall with an iomode of | |||
LAYOUTIOMODE4_RW should cause the client to only return | LAYOUTIOMODE4_RW should cause the client to only return | |||
LAYOUTIOMODE4_RW layouts and not LAYOUTIOMODE4_READ layouts. | LAYOUTIOMODE4_RW layouts and not LAYOUTIOMODE4_READ layouts. | |||
However, a special LAYOUTIOMODE4_ANY enumeration is | However, a special LAYOUTIOMODE4_ANY enumeration is | |||
defined to enable recalling a layout of any iomode; in other words, | defined to enable recalling a layout of any iomode; in other words, | |||
the client must return both LAYOUTIOMODE4_READ and LAYOUTIOMODE4_RW layouts. | the client must return both LAYOUTIOMODE4_READ and LAYOUTIOMODE4_RW layouts. | |||
</t> | </t> | |||
<t> | <t> | |||
A REMOVE operation SHOULD cause the metadata server to recall the | A REMOVE operation <bcp14>SHOULD</bcp14> cause the metadata server to recall t | |||
he | ||||
layout to prevent the client from accessing a non-existent file and | layout to prevent the client from accessing a non-existent file and | |||
to reclaim state stored on the client. Since a REMOVE may be delayed | to reclaim state stored on the client. Since a REMOVE may be delayed | |||
until the last close of the file has occurred, the recall may also | until the last close of the file has occurred, the recall may also | |||
be delayed until this time. After the last reference on the file | be delayed until this time. After the last reference on the file | |||
has been released and the file has been removed, the client should | has been released and the file has been removed, the client should | |||
no longer be able to perform I/O using the layout. In the case of a | no longer be able to perform I/O using the layout. In the case of a | |||
file-based layout, the data server SHOULD return NFS4ERR_STALE in | file-based layout, the data server <bcp14>SHOULD</bcp14> return NFS4ERR_STALE in | |||
response to any operation on the removed file. | response to any operation on the removed file. | |||
</t> | </t> | |||
<t> | <t> | |||
Once a layout has been returned, the client MUST NOT send I/Os to | Once a layout has been returned, the client <bcp14>MUST NOT</bcp14> send I/Os | |||
to | ||||
the storage devices for the file, byte-range, and iomode | the storage devices for the file, byte-range, and iomode | |||
represented by the returned layout. If a client does send an I/O to | represented by the returned layout. If a client does send an I/O to | |||
a storage device for which it does not hold a layout, the storage | a storage device for which it does not hold a layout, the storage | |||
device SHOULD reject the I/O. | device <bcp14>SHOULD</bcp14> reject the I/O. | |||
</t> | </t> | |||
<t anchor="pnfs_and_delegations"> | <t anchor="pnfs_and_delegations"> | |||
Although pNFS does not alter the file data caching capabilities of | Although pNFS does not alter the file data caching capabilities of | |||
clients, or their semantics, it recognizes that some clients may | clients, or their semantics, it recognizes that some clients may | |||
perform more aggressive write-behind caching to optimize the | perform more aggressive write-behind caching to optimize the | |||
benefits provided by pNFS. However, write-behind caching may | benefits provided by pNFS. However, write-behind caching may | |||
negatively affect the latency in returning a layout in response to a | negatively affect the latency in returning a layout in response to a | |||
CB_LAYOUTRECALL; this is similar to file delegations and the impact | CB_LAYOUTRECALL; this is similar to file delegations and the impact | |||
that file data caching has on DELEGRETURN. Client implementations | that file data caching has on DELEGRETURN. Client implementations | |||
SHOULD limit the amount of unwritten data they have outstanding at | <bcp14>SHOULD</bcp14> limit the amount of unwritten data they have outstanding at | |||
any one time in order to prevent excessively long responses to | any one time in order to prevent excessively long responses to | |||
CB_LAYOUTRECALL. Once a layout is recalled, a server MUST wait one | CB_LAYOUTRECALL. Once a layout is recalled, a server <bcp14>MUST</bcp14> wait one | |||
lease period before taking further action. As soon as a lease | lease period before taking further action. As soon as a lease | |||
period has passed, the server may choose to fence the client's access | period has passed, the server may choose to fence the client's access | |||
to the storage devices if the server perceives the client has taken | to the storage devices if the server perceives the client has taken | |||
too long to return a layout. However, just as in the case of data | too long to return a layout. However, just as in the case of data | |||
delegation and DELEGRETURN, the server may choose to wait, given that | delegation and DELEGRETURN, the server may choose to wait, given that | |||
the client is showing forward progress on its way to returning the | the client is showing forward progress on its way to returning the | |||
layout. This forward progress can take the form of successful | layout. This forward progress can take the form of successful | |||
interaction with the storage devices or of sub-portions of the layout | interaction with the storage devices or of sub-portions of the layout | |||
being returned by the client. The server can also limit exposure to | being returned by the client. The server can also limit exposure to | |||
these problems by limiting the byte-ranges initially provided in | these problems by limiting the byte-ranges initially provided in | |||
the layouts and thus the amount of outstanding modified data. | the layouts and thus the amount of outstanding modified data. | |||
</t> | </t> | |||
<section anchor="recall_robustness" numbered="true" toc="default"> | ||||
<section title="Layout Recall Callback Robustness" anchor="recall_robustness"> | <name>Layout Recall Callback Robustness</name> | |||
<t> | <t> | |||
It has been assumed thus far that pNFS client | It has been assumed thus far that pNFS client | |||
state | state | |||
(layout ranges and iomode) | (layout ranges and iomode) | |||
for a file exactly matches that of the pNFS server for that file. | for a file exactly matches that of the pNFS server for that file. | |||
This assumption | This assumption | |||
leads to the implication that any callback results in a | leads to the implication that any callback results in a | |||
LAYOUTRETURN or set of LAYOUTRETURNs that exactly match the range in | LAYOUTRETURN or set of LAYOUTRETURNs that exactly match the range in | |||
the callback, since both client and server agree about the state | the callback, since both client and server agree about the state | |||
being maintained. However, it can be useful if this assumption does | being maintained. However, it can be useful if this assumption does | |||
not always hold. For example: | not always hold. For example: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<list style="symbols"> | <li> | |||
<t> | ||||
If conflicts that require | If conflicts that require | |||
callbacks are very rare, and a server can use a multi-file callback | callbacks are very rare, and a server can use a multi-file callback | |||
to recover per-client resources (e.g., via an FSID recall or a | to recover per-client resources (e.g., via an FSID recall or a | |||
multi-file recall within a single CB_COMPOUND), the result may be | multi-file recall within a single CB_COMPOUND), the result may be | |||
significantly less client-server pNFS traffic. | significantly less client-server pNFS traffic. | |||
</t> | </li> | |||
<t> | <li> | |||
It may be useful for servers to maintain information about | It may be useful for servers to maintain information about | |||
what ranges are held by a client on a coarse-grained basis, leading | what ranges are held by a client on a coarse-grained basis, leading | |||
to the server's layout ranges being beyond those actually held by | to the server's layout ranges being beyond those actually held by | |||
the client. | the client. | |||
In the extreme, a server could manage conflicts on | In the extreme, a server could manage conflicts on | |||
a per-file basis, only sending whole-file callbacks even though | a per-file basis, only sending whole-file callbacks even though | |||
clients may request and be granted sub-file ranges. | clients may request and be granted sub-file ranges. | |||
</t> | </li> | |||
<t> | <li> | |||
It may be useful for clients to "forget" details about | It may be useful for clients to "forget" details about | |||
what layouts and ranges the client actually has, leading | what layouts and ranges the client actually has, leading | |||
to the server's layout ranges being beyond those that the | to the server's layout ranges being beyond those that the | |||
client "thinks" it has. As long as the client does not | client "thinks" it has. As long as the client does not | |||
assume it has layouts that are beyond what the server | assume it has layouts that are beyond what the server | |||
has granted, this is a safe practice. When a client | has granted, this is a safe practice. When a client | |||
forgets what ranges and layouts it has, and it receives | forgets what ranges and layouts it has, and it receives | |||
a CB_LAYOUTRECALL operation, the client MUST follow up | a CB_LAYOUTRECALL operation, the client <bcp14>MUST</bcp14> follow up | |||
with a LAYOUTRETURN for what the server recalled, or | with a LAYOUTRETURN for what the server recalled, or | |||
alternatively return the NFS4ERR_NOMATCHING_LAYOUT error | alternatively return the NFS4ERR_NOMATCHING_LAYOUT error | |||
if it has no layout to return in the recalled range. | if it has no layout to return in the recalled range. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
In order to avoid errors, it is vital that a client not assign | In order to avoid errors, it is vital that a client not assign | |||
itself layout permissions beyond what the server has granted, and | itself layout permissions beyond what the server has granted, and | |||
that the server not forget layout permissions that have been granted. | that the server not forget layout permissions that have been granted. | |||
On the other hand, if a | On the other hand, if a | |||
server believes that a client holds a layout that the client | server believes that a client holds a layout that the client | |||
does not know about, it is useful for the client to cleanly indicate | does not know about, it is useful for the client to cleanly indicate | |||
completion of the requested recall either by sending a LAYOUTRETURN | completion of the requested recall either by sending a LAYOUTRETURN | |||
operation for the entire requested range or by returning an | operation for the entire requested range or by returning an | |||
NFS4ERR_NOMATCHING_LAYOUT error to the CB_LAYOUTRECALL. | NFS4ERR_NOMATCHING_LAYOUT error to the CB_LAYOUTRECALL. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Thus, in light of the above, it is useful for a server to be able to | Thus, in light of the above, it is useful for a server to be able to | |||
send callbacks for layout ranges it has not granted to a client, | send callbacks for layout ranges it has not granted to a client, | |||
and for a client to return ranges it does not hold. A pNFS client | and for a client to return ranges it does not hold. A pNFS client | |||
MUST always return layouts that comprise the full range | <bcp14>MUST</bcp14> always return layouts that comprise the full range | |||
specified by the recall. Note, the full recalled layout range need | specified by the recall. Note, the full recalled layout range need | |||
not be returned as part of a single operation, but may be returned | not be returned as part of a single operation, but may be returned | |||
in portions. This allows the client to stage the flushing of dirty | in portions. This allows the client to stage the flushing of dirty | |||
data and commits and returns of layouts. | data and commits and returns of layouts. | |||
Also, it indicates to the | Also, it indicates to the | |||
metadata server that the client is making progress. | metadata server that the client is making progress. | |||
</t> | </t> | |||
<t> | <t> | |||
When a layout is returned, the client MUST NOT have any outstanding | When a layout is returned, the client <bcp14>MUST NOT</bcp14> have any outstan | |||
ding | ||||
I/O requests to the storage devices involved in the layout. | I/O requests to the storage devices involved in the layout. | |||
Rephrasing, the client MUST NOT return the layout while it has | Rephrasing, the client <bcp14>MUST NOT</bcp14> return the layout while it has | |||
outstanding I/O requests to the storage device. | outstanding I/O requests to the storage device. | |||
</t> | </t> | |||
<t> | <t> | |||
Even with this requirement for the client, it is possible that I/O | Even with this requirement for the client, it is possible that I/O | |||
requests may be presented to a storage device no longer allowed to | requests may be presented to a storage device no longer allowed to | |||
perform them. Since the server has no strict control as to when the | perform them. Since the server has no strict control as to when the | |||
client will return the layout, the server may later decide to | client will return the layout, the server may later decide to | |||
unilaterally revoke the client's access to the storage devices | unilaterally revoke the client's access to the storage devices | |||
as provided by the layout. In | as provided by the layout. In | |||
choosing to revoke access, the server must deal with the possibility | choosing to revoke access, the server must deal with the possibility | |||
of lingering I/O requests, i.e., I/O requests that are | of lingering I/O requests, i.e., I/O requests that are | |||
still in flight to | still in flight to | |||
storage devices identified by the revoked layout. | storage devices identified by the revoked layout. | |||
All layout type specifications MUST define whether unilateral layout revocatio n by | All layout type specifications <bcp14>MUST</bcp14> define whether unilateral l ayout revocation by | |||
the metadata server is supported; if it is, the specification must | the metadata server is supported; if it is, the specification must | |||
also describe how lingering writes are processed. For example, | also describe how lingering writes are processed. For example, | |||
storage devices identified by the revoked layout could be fenced off | storage devices identified by the revoked layout could be fenced off | |||
from the client that held the layout. | from the client that held the layout. | |||
</t> | </t> | |||
<t> | <t> | |||
In order to ensure client/server convergence with regard to layout state, | In order to ensure client/server convergence with regard to layout state, | |||
the final LAYOUTRETURN operation in a sequence of LAYOUTRETURN | the final LAYOUTRETURN operation in a sequence of LAYOUTRETURN | |||
operations for a particular recall MUST specify the entire range | operations for a particular recall <bcp14>MUST</bcp14> specify the entire rang e | |||
being recalled, echoing the recalled layout type, iomode, | being recalled, echoing the recalled layout type, iomode, | |||
recall/return type (FILE, FSID, or ALL), and byte-range, even if | recall/return type (FILE, FSID, or ALL), and byte-range, even if | |||
layouts pertaining to partial ranges were previously | layouts pertaining to partial ranges were previously | |||
returned. In addition, if the client holds no layouts that | returned. In addition, if the client holds no layouts that | |||
overlap the range being recalled, the client should return the | overlap the range being recalled, the client should return the | |||
NFS4ERR_NOMATCHING_LAYOUT error code to CB_LAYOUTRECALL. This | NFS4ERR_NOMATCHING_LAYOUT error code to CB_LAYOUTRECALL. This | |||
allows the server to update its view of the client's layout state. | allows the server to update its view of the client's layout state. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="pnfs_operation_sequencing" numbered="true" toc="defau | ||||
<section title="Sequencing of Layout Operations" anchor="pnfs_operation_sequenci | lt"> | |||
ng"> | <name>Sequencing of Layout Operations</name> | |||
<t> | <t> | |||
As with other stateful operations, pNFS requires the correct | As with other stateful operations, pNFS requires the correct | |||
sequencing of layout operations. pNFS uses the "seqid" in the | sequencing of layout operations. pNFS uses the "seqid" in the | |||
layout stateid to provide the correct sequencing between regular | layout stateid to provide the correct sequencing between regular | |||
operations and callbacks. It is the server's responsibility to | operations and callbacks. It is the server's responsibility to | |||
avoid inconsistencies regarding the layouts provided and the | avoid inconsistencies regarding the layouts provided and the | |||
client's responsibility to properly serialize its layout requests | client's responsibility to properly serialize its layout requests | |||
and layout returns. | and layout returns. | |||
</t> | </t> | |||
<section title="Layout Recall and Return Sequencing"> | <section numbered="true" toc="default"> | |||
<t> | <name>Layout Recall and Return Sequencing</name> | |||
<t> | ||||
One critical issue with regard to layout operations sequencing | One critical issue with regard to layout operations sequencing | |||
concerns callbacks. The protocol must defend against | concerns callbacks. The protocol must defend against | |||
races between the reply to a LAYOUTGET or LAYOUTRETURN | races between the reply to a LAYOUTGET or LAYOUTRETURN | |||
operation and a subsequent CB_LAYOUTRECALL. A client | operation and a subsequent CB_LAYOUTRECALL. A client | |||
MUST NOT process a CB_LAYOUTRECALL that implies one or | <bcp14>MUST NOT</bcp14> process a CB_LAYOUTRECALL that implies one or | |||
more outstanding LAYOUTGET or LAYOUTRETURN operations to | more outstanding LAYOUTGET or LAYOUTRETURN operations to | |||
which the client has not yet received a reply. The client | which the client has not yet received a reply. The client | |||
detects such a CB_LAYOUTRECALL by examining the "seqid" | detects such a CB_LAYOUTRECALL by examining the "seqid" | |||
field of the recall's layout stateid. If the "seqid" | field of the recall's layout stateid. If the "seqid" | |||
is not exactly one higher than what the client currently has recorded, and the | is not exactly one higher than what the client currently has recorded, and the | |||
client has at least one LAYOUTGET and/or LAYOUTRETURN operation | client has at least one LAYOUTGET and/or LAYOUTRETURN operation | |||
outstanding, the client knows the server sent the CB_LAYOUTRECALL | outstanding, the client knows the server sent the CB_LAYOUTRECALL | |||
after sending a response to an outstanding LAYOUTGET or LAYOUTRETURN. | after sending a response to an outstanding LAYOUTGET or LAYOUTRETURN. | |||
The client MUST wait before processing such a CB_LAYOUTRECALL | The client <bcp14>MUST</bcp14> wait before processing such a CB_LAYOUTRECALL | |||
until it processes all replies for outstanding LAYOUTGET and | until it processes all replies for outstanding LAYOUTGET and | |||
LAYOUTRETURN operations for the corresponding file | LAYOUTRETURN operations for the corresponding file | |||
with seqid less than the seqid given by CB_LAYOUTRECALL | with seqid less than the seqid given by CB_LAYOUTRECALL | |||
(lor_stateid; see <xref target="OP_CB_LAYOUTRECALL"/>.) | (lor_stateid; see <xref target="OP_CB_LAYOUTRECALL" format="default"/>.) | |||
</t> | </t> | |||
<t> | <t> | |||
In addition to the seqid-based mechanism, | In addition to the seqid-based mechanism, | |||
<xref target="sessions_callback_races"/> | <xref target="sessions_callback_races" format="default"/> | |||
describes the sessions mechanism for allowing the | describes the sessions mechanism for allowing the | |||
client to detect callback race conditions and delay processing such a | client to detect callback race conditions and delay processing such a | |||
CB_LAYOUTRECALL. The server MAY reference conflicting operations | CB_LAYOUTRECALL. The server <bcp14>MAY</bcp14> reference conflicting operation s | |||
in the CB_SEQUENCE that precedes the CB_LAYOUTRECALL. | in the CB_SEQUENCE that precedes the CB_LAYOUTRECALL. | |||
Because the server has already sent replies for these operations before | Because the server has already sent replies for these operations before | |||
sending the callback, the replies may race with the CB_LAYOUTRECALL. | sending the callback, the replies may race with the CB_LAYOUTRECALL. | |||
The client MUST wait for all the referenced calls to complete and update | The client <bcp14>MUST</bcp14> wait for all the referenced calls to complete a nd update | |||
its view of the layout state before processing the CB_LAYOUTRECALL. | its view of the layout state before processing the CB_LAYOUTRECALL. | |||
</t> | </t> | |||
<section numbered="true" toc="default"> | ||||
<section title="Get/Return Sequencing"> | <name>Get/Return Sequencing</name> | |||
<t> | <t> | |||
The protocol allows the client to send concurrent | The protocol allows the client to send concurrent | |||
LAYOUTGET and LAYOUTRETURN operations to the server. The | LAYOUTGET and LAYOUTRETURN operations to the server. The | |||
protocol does not provide any means for the server to | protocol does not provide any means for the server to | |||
process the requests in the same order in which they | process the requests in the same order in which they | |||
were created. However, through the use of the "seqid" | were created. However, through the use of the "seqid" | |||
field in the layout stateid, the client can determine | field in the layout stateid, the client can determine | |||
the order in which parallel outstanding operations were | the order in which parallel outstanding operations were | |||
processed by the server. Thus, when a layout retrieved | processed by the server. Thus, when a layout retrieved | |||
by an outstanding LAYOUTGET operation intersects with | by an outstanding LAYOUTGET operation intersects with | |||
a layout returned by an outstanding LAYOUTRETURN on | a layout returned by an outstanding LAYOUTRETURN on | |||
the same file, the order in which the two conflicting | the same file, the order in which the two conflicting | |||
operations are processed determines the final state of | operations are processed determines the final state of | |||
the overlapping layout. The order is determined by | the overlapping layout. The order is determined by | |||
the "seqid" returned in each operation: the operation with the | the "seqid" returned in each operation: the operation with the | |||
higher seqid was executed later. | higher seqid was executed later. | |||
</t> | </t> | |||
<t> | <t> | |||
It is permissible for the client to send multiple parallel | It is permissible for the client to send multiple parallel | |||
LAYOUTGET operations for the same file or multiple parallel LAYOUTRETURN | LAYOUTGET operations for the same file or multiple parallel LAYOUTRETURN | |||
operations for the same file or a mix of both. | operations for the same file or a mix of both. | |||
</t> | </t> | |||
<t> | <t> | |||
It is permissible for the client to use the current stateid (see | It is permissible for the client to use the current stateid (see | |||
<xref target="current_stateid"/>) for LAYOUTGET operations, for | <xref target="current_stateid" format="default"/>) for LAYOUTGET operations, f or | |||
example, when compounding LAYOUTGETs or compounding OPEN and | example, when compounding LAYOUTGETs or compounding OPEN and | |||
LAYOUTGETs. It is also permissible to use the current stateid when | LAYOUTGETs. It is also permissible to use the current stateid when | |||
compounding LAYOUTRETURNs. | compounding LAYOUTRETURNs. | |||
</t> | </t> | |||
<t> | <t> | |||
It is permissible for the client to use the current stateid when | It is permissible for the client to use the current stateid when | |||
combining LAYOUTRETURN and LAYOUTGET operations for the same file in | combining LAYOUTRETURN and LAYOUTGET operations for the same file in | |||
the same COMPOUND request since the server MUST process these in | the same COMPOUND request since the server <bcp14>MUST</bcp14> process these i n | |||
order. However, if a client does send such COMPOUND requests, it | order. However, if a client does send such COMPOUND requests, it | |||
MUST NOT have more than one outstanding for the same file at the | <bcp14>MUST NOT</bcp14> have more than one outstanding for the same file at th | |||
same time, and it MUST NOT have other LAYOUTGET or LAYOUTRETURN | e | |||
same time, and it <bcp14>MUST NOT</bcp14> have other LAYOUTGET or LAYOUTRETURN | ||||
operations outstanding at the same time for that same file. | operations outstanding at the same time for that same file. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="Client Considerations"> | <name>Client Considerations</name> | |||
<t> | <t> | |||
Consider a pNFS client that has sent a LAYOUTGET, and before | Consider a pNFS client that has sent a LAYOUTGET, and before | |||
it receives the reply to LAYOUTGET, it receives | it receives the reply to LAYOUTGET, it receives | |||
a CB_LAYOUTRECALL for the same file with an overlapping range. There are two | a CB_LAYOUTRECALL for the same file with an overlapping range. There are two | |||
possibilities, which the client can distinguish | possibilities, which the client can distinguish | |||
via the layout stateid in the recall. | via the layout stateid in the recall. | |||
<list style="numbers"> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
The server processed the LAYOUTGET before sending the recall, so the | The server processed the LAYOUTGET before sending the recall, so the | |||
LAYOUTGET must be waited for because it | LAYOUTGET must be waited for because it | |||
may be carrying layout information that will need to be returned to deal | may be carrying layout information that will need to be returned to deal | |||
with the CB_LAYOUTRECALL. | with the CB_LAYOUTRECALL. | |||
</t> | </li> | |||
<t> | <li> | |||
The | The | |||
server sent the callback before receiving the | server sent the callback before receiving the | |||
LAYOUTGET. The server will not respond to the LAYOUTGET | LAYOUTGET. The server will not respond to the LAYOUTGET | |||
until the CB_LAYOUTRECALL is processed. | until the CB_LAYOUTRECALL is processed. | |||
</t> | </li> | |||
</list> | </ol> | |||
<t> | ||||
If these possibilities cannot be distinguished, a | If these possibilities cannot be distinguished, a | |||
deadlock could result, as the client must wait for the | deadlock could result, as the client must wait for the | |||
LAYOUTGET response before processing the recall in the | LAYOUTGET response before processing the recall in the | |||
first case, but that response will not arrive until after | first case, but that response will not arrive until after | |||
the recall is processed in the second case. Note that | the recall is processed in the second case. Note that | |||
in the first case, the "seqid" in the layout stateid | in the first case, the "seqid" in the layout stateid | |||
of the recall is two greater than what the client has | of the recall is two greater than what the client has | |||
recorded; in the second case, the "seqid" is one greater than | recorded; in the second case, the "seqid" is one greater than | |||
what the client has recorded. This allows the client | what the client has recorded. This allows the client | |||
to disambiguate between the two cases. The client thus | to disambiguate between the two cases. The client thus | |||
knows precisely which possibility applies. | knows precisely which possibility applies. | |||
</t> | </t> | |||
<t> | <t> | |||
In case 1, the client knows it needs to wait for | In case 1, the client knows it needs to wait for | |||
the LAYOUTGET response before processing the recall | the LAYOUTGET response before processing the recall | |||
(or the client can return NFS4ERR_DELAY). | (or the client can return NFS4ERR_DELAY). | |||
</t> | </t> | |||
<t> | <t> | |||
In case 2, the client will not wait for the LAYOUTGET | In case 2, the client will not wait for the LAYOUTGET | |||
response before processing the recall because waiting | response before processing the recall because waiting | |||
would cause deadlock. Therefore, the action at the | would cause deadlock. Therefore, the action at the | |||
client will only require waiting in the case that the | client will only require waiting in the case that the | |||
client has not yet seen the server's earlier responses | client has not yet seen the server's earlier responses | |||
to the LAYOUTGET operation(s). | to the LAYOUTGET operation(s). | |||
</t> | </t> | |||
<t> | <t> | |||
The recall process can be considered completed when | The recall process can be considered completed when | |||
the final LAYOUTRETURN operation for the recalled range is completed. | the final LAYOUTRETURN operation for the recalled range is completed. | |||
The LAYOUTRETURN uses the layout stateid (with seqid) specified in | The LAYOUTRETURN uses the layout stateid (with seqid) specified in | |||
CB_LAYOUTRECALL. If the client uses multiple LAYOUTRETURNs in | CB_LAYOUTRECALL. If the client uses multiple LAYOUTRETURNs in | |||
processing the recall, the first LAYOUTRETURN will use the layout | processing the recall, the first LAYOUTRETURN will use the layout | |||
stateid as specified in CB_LAYOUTRECALL. Subsequent LAYOUTRETURNs | stateid as specified in CB_LAYOUTRECALL. Subsequent LAYOUTRETURNs | |||
will use the highest seqid as is the usual case. | will use the highest seqid as is the usual case. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section anchor="layout_server_consider" numbered="true" toc="defa | |||
ult"> | ||||
<section title="Server Considerations" anchor="layout_server_consider"> | <name>Server Considerations</name> | |||
<t> | <t> | |||
Consider a race from the metadata server's point of | Consider a race from the metadata server's point of | |||
view. The metadata server has sent a CB_LAYOUTRECALL and receives | view. The metadata server has sent a CB_LAYOUTRECALL and receives | |||
an overlapping LAYOUTGET for the same file before the | an overlapping LAYOUTGET for the same file before the | |||
LAYOUTRETURN(s) that respond to the CB_LAYOUTRECALL. There are | LAYOUTRETURN(s) that respond to the CB_LAYOUTRECALL. There are | |||
three cases: | three cases: | |||
<list style="numbers"> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
The client sent the LAYOUTGET before processing the CB_LAYOUTRECALL. | The client sent the LAYOUTGET before processing the CB_LAYOUTRECALL. | |||
The "seqid" in the layout stateid of the arguments of LAYOUTGET is one less | The "seqid" in the layout stateid of the arguments of LAYOUTGET is one less | |||
than the "seqid" in CB_LAYOUTRECALL. The server returns | than the "seqid" in CB_LAYOUTRECALL. The server returns | |||
NFS4ERR_RECALLCONFLICT to the client, which indicates to the client | NFS4ERR_RECALLCONFLICT to the client, which indicates to the client | |||
that there is a pending recall. | that there is a pending recall. | |||
</t> | </li> | |||
<t> | <li> | |||
The client sent the LAYOUTGET after processing the | The client sent the LAYOUTGET after processing the | |||
CB_LAYOUTRECALL, but the LAYOUTGET arrived before the LAYOUTRETURN and | CB_LAYOUTRECALL, but the LAYOUTGET arrived before the LAYOUTRETURN and | |||
the response to CB_LAYOUTRECALL that | the response to CB_LAYOUTRECALL that | |||
completed that processing. | completed that processing. | |||
The "seqid" in the layout stateid | The "seqid" in the layout stateid | |||
of LAYOUTGET is equal to or greater than that of the "seqid" in | of LAYOUTGET is equal to or greater than that of the "seqid" in | |||
CB_LAYOUTRECALL. | CB_LAYOUTRECALL. | |||
The server has not received a response to the CB_LAYOUTRECALL, | The server has not received a response to the CB_LAYOUTRECALL, | |||
so it returns NFS4ERR_RECALLCONFLICT. | so it returns NFS4ERR_RECALLCONFLICT. | |||
</t> | </li> | |||
<t> | <li> | |||
The client sent the LAYOUTGET after processing the | The client sent the LAYOUTGET after processing the | |||
CB_LAYOUTRECALL; the server received the CB_LAYOUTRECALL | CB_LAYOUTRECALL; the server received the CB_LAYOUTRECALL | |||
response, but the LAYOUTGET arrived before the LAYOUTRETURN that | response, but the LAYOUTGET arrived before the LAYOUTRETURN that | |||
completed that processing. | completed that processing. | |||
The "seqid" in the layout stateid | The "seqid" in the layout stateid | |||
of LAYOUTGET is equal to that of the "seqid" in | of LAYOUTGET is equal to that of the "seqid" in | |||
CB_LAYOUTRECALL. | CB_LAYOUTRECALL. | |||
The server has received a response to the CB_LAYOUTRECALL, | The server has received a response to the CB_LAYOUTRECALL, | |||
so it returns NFS4ERR_RETURNCONFLICT. | so it returns NFS4ERR_RETURNCONFLICT. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | </section> | |||
<section numbered="true" toc="default"> | ||||
</section> | <name>Wraparound and Validation of Seqid</name> | |||
<t> | ||||
<section title="Wraparound and Validation of Seqid"> | ||||
<t> | ||||
The rules for layout stateid processing differ from other stateids | The rules for layout stateid processing differ from other stateids | |||
in the protocol because the "seqid" value cannot be zero and the | in the protocol because the "seqid" value cannot be zero and the | |||
stateid's "seqid" value changes in a CB_LAYOUTRECALL operation. The | stateid's "seqid" value changes in a CB_LAYOUTRECALL operation. The | |||
non-zero requirement combined with the inherent parallelism of | non-zero requirement combined with the inherent parallelism of | |||
layout operations means that a set of LAYOUTGET and LAYOUTRETURN | layout operations means that a set of LAYOUTGET and LAYOUTRETURN | |||
operations may contain the same value for "seqid". | operations may contain the same value for "seqid". | |||
The server uses a slightly modified version of the modulo arithmetic | The server uses a slightly modified version of the modulo arithmetic | |||
as described in | as described in | |||
<xref target="Slot_Identifiers_and_Server_Reply_Cache" /> | <xref target="Slot_Identifiers_and_Server_Reply_Cache" format="default"/> | |||
when incrementing the layout stateid's "seqid". The difference | when incrementing the layout stateid's "seqid". The difference | |||
is that zero is not a valid value for "seqid"; when the value | is that zero is not a valid value for "seqid"; when the value | |||
of a "seqid" is 0xFFFFFFFF, the next valid value will be 0x00000001. | of a "seqid" is 0xFFFFFFFF, the next valid value will be 0x00000001. | |||
The modulo arithmetic is also used for the comparisons of | The modulo arithmetic is also used for the comparisons of | |||
"seqid" values in the processing of CB_LAYOUTRECALL events as | "seqid" values in the processing of CB_LAYOUTRECALL events as | |||
described above in <xref target="layout_server_consider" />. | described above in <xref target="layout_server_consider" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
Just as the server validates the "seqid" in the event of | Just as the server validates the "seqid" in the event of | |||
CB_LAYOUTRECALL usage, as described in | CB_LAYOUTRECALL usage, as described in | |||
<xref target="layout_server_consider" />, the server also validates | <xref target="layout_server_consider" format="default"/>, the server also vali dates | |||
the "seqid" value to ensure that it is within an appropriate range. | the "seqid" value to ensure that it is within an appropriate range. | |||
This range represents the degree of parallelism the server supports | This range represents the degree of parallelism the server supports | |||
for layout stateids. If the client is sending multiple layout | for layout stateids. If the client is sending multiple layout | |||
operations to the server in parallel, by definition, the "seqid" | operations to the server in parallel, by definition, the "seqid" | |||
value in the supplied stateid will not be the current "seqid" as | value in the supplied stateid will not be the current "seqid" as | |||
held by the server. The range of parallelism spans from the highest | held by the server. The range of parallelism spans from the highest | |||
or current "seqid" to a "seqid" value in the past. To assist in the | or current "seqid" to a "seqid" value in the past. To assist in the | |||
discussion, the server's current "seqid" value for a layout stateid | discussion, the server's current "seqid" value for a layout stateid | |||
is defined as SERVER_CURRENT_SEQID. The lowest "seqid" value that | is defined as SERVER_CURRENT_SEQID. The lowest "seqid" value that | |||
is acceptable to the server is represented by PAST_SEQID. And the | is acceptable to the server is represented by PAST_SEQID. And the | |||
value for the range of valid "seqid"s or range of parallelism is | value for the range of valid "seqid"s or range of parallelism is | |||
VALID_SEQID_RANGE. Therefore, the following holds: | VALID_SEQID_RANGE. Therefore, the following holds: | |||
VALID_SEQID_RANGE = SERVER_CURRENT_SEQID - PAST_SEQID. In the | VALID_SEQID_RANGE = SERVER_CURRENT_SEQID - PAST_SEQID. In the | |||
following, all arithmetic is the modulo arithmetic as described | following, all arithmetic is the modulo arithmetic as described | |||
above. | above. | |||
</t> | </t> | |||
<t> | <t> | |||
The server MUST support a minimum VALID_SEQID_RANGE. The minimum is | The server <bcp14>MUST</bcp14> support a minimum VALID_SEQID_RANGE. The minim | |||
um is | ||||
defined as: VALID_SEQID_RANGE = summation over 1..N of | defined as: VALID_SEQID_RANGE = summation over 1..N of | |||
(ca_maxoperations(i) - 1), where N is the number of session fore | (ca_maxoperations(i) - 1), where N is the number of session fore | |||
channels and ca_maxoperations(i) is the value of the ca_maxoperations returned from | channels and ca_maxoperations(i) is the value of the ca_maxoperations returned from | |||
CREATE_SESSION of the i'th session. The reason for "- 1" is to allow for the required | CREATE_SESSION of the i'th session. The reason for "- 1" is to allow for the required | |||
SEQUENCE operation. The server MAY support a VALID_SEQID_RANGE | SEQUENCE operation. The server <bcp14>MAY</bcp14> support a VALID_SEQID_RANGE | |||
value larger than the minimum. The maximum VALID_SEQID_RANGE is (2 | value larger than the minimum. The maximum VALID_SEQID_RANGE is (2<sup>32</su | |||
^ 32 - 2) (accounting for zero not being a valid "seqid" value). | p> - 2) (accounting for zero not being a valid "seqid" value). | |||
</t> | </t> | |||
<t> | <t> | |||
If the server finds the "seqid" is zero, the NFS4ERR_BAD_STATEID | If the server finds the "seqid" is zero, the NFS4ERR_BAD_STATEID | |||
error is returned to the client. The server further validates the | error is returned to the client. The server further validates the | |||
"seqid" to ensure it is within the range of parallelism, | "seqid" to ensure it is within the range of parallelism, | |||
VALID_SEQID_RANGE. If the "seqid" value is outside of that range, | VALID_SEQID_RANGE. If the "seqid" value is outside of that range, | |||
the error NFS4ERR_OLD_STATEID is returned to the client. Upon | the error NFS4ERR_OLD_STATEID is returned to the client. Upon | |||
receipt of NFS4ERR_OLD_STATEID, the client updates the stateid in | receipt of NFS4ERR_OLD_STATEID, the client updates the stateid in | |||
the layout request based on processing of other layout requests and | the layout request based on processing of other layout requests and | |||
re-sends the operation to the server. | re-sends the operation to the server. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="bulk_layouts" numbered="true" toc="default"> | ||||
<section title="Bulk Recall and Return" anchor="bulk_layouts"> | <name>Bulk Recall and Return</name> | |||
<t> | ||||
<t> | ||||
pNFS supports recalling and returning all layouts that | pNFS supports recalling and returning all layouts that | |||
are for files belonging to a particular fsid | are for files belonging to a particular fsid | |||
(LAYOUTRECALL4_FSID, LAYOUTRETURN4_FSID) or client ID | (LAYOUTRECALL4_FSID, LAYOUTRETURN4_FSID) or client ID | |||
(LAYOUTRECALL4_ALL, LAYOUTRETURN4_ALL). | (LAYOUTRECALL4_ALL, LAYOUTRETURN4_ALL). | |||
There are no "bulk" stateids, so detection of races | There are no "bulk" stateids, so detection of races | |||
via the seqid is not possible. | via the seqid is not possible. | |||
The server MUST NOT initiate bulk recall while another | The server <bcp14>MUST NOT</bcp14> initiate bulk recall while another | |||
recall is in progress, or the corresponding LAYOUTRETURN | recall is in progress, or the corresponding LAYOUTRETURN | |||
is in progress or pending. | is in progress or pending. | |||
In the event the server sends a bulk recall | In the event the server sends a bulk recall | |||
while the client has a pending or in-progress LAYOUTRETURN, | while the client has a pending or in-progress LAYOUTRETURN, | |||
CB_LAYOUTRECALL, or LAYOUTGET, the client returns | CB_LAYOUTRECALL, or LAYOUTGET, the client returns | |||
NFS4ERR_DELAY. In the event the client sends a LAYOUTGET | NFS4ERR_DELAY. In the event the client sends a LAYOUTGET | |||
or LAYOUTRETURN while a bulk recall is in progress, the | or LAYOUTRETURN while a bulk recall is in progress, the | |||
server returns NFS4ERR_RECALLCONFLICT. | server returns NFS4ERR_RECALLCONFLICT. | |||
If the client sends a LAYOUTGET or LAYOUTRETURN after | If the client sends a LAYOUTGET or LAYOUTRETURN after | |||
the server receives NFS4ERR_DELAY from a bulk recall, | the server receives NFS4ERR_DELAY from a bulk recall, | |||
then to ensure forward progress, the server MAY return | then to ensure forward progress, the server <bcp14>MAY</bcp14> return | |||
NFS4ERR_RECALLCONFLICT. | NFS4ERR_RECALLCONFLICT. | |||
</t> | </t> | |||
<t> | <t> | |||
Once a CB_LAYOUTRECALL of LAYOUTRECALL4_ALL is sent, | Once a CB_LAYOUTRECALL of LAYOUTRECALL4_ALL is sent, | |||
the server MUST NOT allow the client to use any layout | the server <bcp14>MUST NOT</bcp14> allow the client to use any layout | |||
stateid except for LAYOUTCOMMIT operations. Once the client receives | stateid except for LAYOUTCOMMIT operations. Once the client receives | |||
a CB_LAYOUTRECALL of LAYOUTRECALL4_ALL, it MUST NOT use | a CB_LAYOUTRECALL of LAYOUTRECALL4_ALL, it <bcp14>MUST NOT</bcp14> use | |||
any layout stateid except for LAYOUTCOMMIT operations. | any layout stateid except for LAYOUTCOMMIT operations. | |||
Once a LAYOUTRETURN of LAYOUTRETURN4_ALL is sent, all | Once a LAYOUTRETURN of LAYOUTRETURN4_ALL is sent, all | |||
layout stateids granted to the client ID are freed. | layout stateids granted to the client ID are freed. | |||
The client MUST NOT use the layout stateids again. It | The client <bcp14>MUST NOT</bcp14> use the layout stateids again. It | |||
MUST use LAYOUTGET to obtain new layout stateids. | <bcp14>MUST</bcp14> use LAYOUTGET to obtain new layout stateids. | |||
</t> | </t> | |||
<t> | <t> | |||
Once a CB_LAYOUTRECALL of LAYOUTRECALL4_FSID is sent, the | Once a CB_LAYOUTRECALL of LAYOUTRECALL4_FSID is sent, the | |||
server MUST NOT allow the client to use any layout stateid | server <bcp14>MUST NOT</bcp14> allow the client to use any layout stateid | |||
that refers to a file with the specified fsid except for | that refers to a file with the specified fsid except for | |||
LAYOUTCOMMIT operations. Once the client receives a CB_LAYOUTRECALL | LAYOUTCOMMIT operations. Once the client receives a CB_LAYOUTRECALL | |||
of LAYOUTRECALL4_ALL, it MUST NOT use any layout stateid | of LAYOUTRECALL4_ALL, it <bcp14>MUST NOT</bcp14> use any layout stateid | |||
that refers to a file with the specified fsid except | that refers to a file with the specified fsid except | |||
for LAYOUTCOMMIT operations. | for LAYOUTCOMMIT operations. | |||
Once a LAYOUTRETURN of LAYOUTRETURN4_FSID is sent, all | Once a LAYOUTRETURN of LAYOUTRETURN4_FSID is sent, all | |||
layout stateids granted to the referenced fsid are freed. | layout stateids granted to the referenced fsid are freed. | |||
The client MUST NOT use those freed layout stateids for files | The client <bcp14>MUST NOT</bcp14> use those freed layout stateids for files | |||
with the referenced fsid again. Subsequently, for any file with | with the referenced fsid again. Subsequently, for any file with | |||
the referenced fsid, to use a layout, the client MUST first | the referenced fsid, to use a layout, the client <bcp14>MUST</bcp14> first | |||
send a LAYOUTGET operation in order to | send a LAYOUTGET operation in order to | |||
obtain a new layout stateid for that file. | obtain a new layout stateid for that file. | |||
</t> | </t> | |||
<t> | <t> | |||
If the server has sent a bulk CB_LAYOUTRECALL and | If the server has sent a bulk CB_LAYOUTRECALL and | |||
receives a LAYOUTGET, or a LAYOUTRETURN with a stateid, | receives a LAYOUTGET, or a LAYOUTRETURN with a stateid, | |||
the server MUST return NFS4ERR_RECALLCONFLICT. If the | the server <bcp14>MUST</bcp14> return NFS4ERR_RECALLCONFLICT. If the | |||
server has sent a bulk CB_LAYOUTRECALL and receives a | server has sent a bulk CB_LAYOUTRECALL and receives a | |||
LAYOUTRETURN with an lr_returntype that is not equal to | LAYOUTRETURN with an lr_returntype that is not equal to | |||
the lor_recalltype of the CB_LAYOUTRECALL, the server | the lor_recalltype of the CB_LAYOUTRECALL, the server | |||
MUST return NFS4ERR_RECALLCONFLICT. | <bcp14>MUST</bcp14> return NFS4ERR_RECALLCONFLICT. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | ||||
</section> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="revoke_layout" numbered="true" toc="default"> | |||
<name>Revoking Layouts</name> | ||||
<section title="Revoking Layouts" anchor="revoke_layout"> | <t> | |||
<t> | ||||
Parallel NFS permits servers to revoke layouts from clients | Parallel NFS permits servers to revoke layouts from clients | |||
that fail to respond to recalls and/or fail to renew their | that fail to respond to recalls and/or fail to renew their | |||
lease in time. Depending on the layout type, | lease in time. Depending on the layout type, | |||
the server might revoke the layout and might take certain actions | the server might revoke the layout and might take certain actions | |||
with respect to the client's I/O to data servers. | with respect to the client's I/O to data servers. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Metadata Server Write Propagation" anchor="async_writes"> | <section anchor="async_writes" numbered="true" toc="default"> | |||
<t> | <name>Metadata Server Write Propagation</name> | |||
<t> | ||||
Asynchronous writes written through the metadata server may be | Asynchronous writes written through the metadata server may be | |||
propagated lazily to the storage devices. For data written | propagated lazily to the storage devices. For data written | |||
asynchronously through the metadata server, a client performing a | asynchronously through the metadata server, a client performing a | |||
read at the appropriate storage device is not guaranteed to see the | read at the appropriate storage device is not guaranteed to see the | |||
newly written data until a COMMIT occurs at the metadata server. | newly written data until a COMMIT occurs at the metadata server. | |||
While the write is pending, reads to the storage device may give out | While the write is pending, reads to the storage device may give out | |||
either the old data, the new data, or a mixture of new and old. | either the old data, the new data, or a mixture of new and old. | |||
Upon completion of a synchronous WRITE or COMMIT (for asynchronously | Upon completion of a synchronous WRITE or COMMIT (for asynchronously | |||
written data), the metadata server MUST ensure that storage devices | written data), the metadata server <bcp14>MUST</bcp14> ensure that storage dev ices | |||
give out the new data and that the data has been written to stable | give out the new data and that the data has been written to stable | |||
storage. If the server implements its storage in any way such that | storage. If the server implements its storage in any way such that | |||
it cannot obey these constraints, then it MUST recall the layouts to | it cannot obey these constraints, then it <bcp14>MUST</bcp14> recall the layou ts to | |||
prevent reads being done that cannot be handled correctly. Note | prevent reads being done that cannot be handled correctly. Note | |||
that the layouts MUST be recalled prior to the server responding to | that the layouts <bcp14>MUST</bcp14> be recalled prior to the server respondin g to | |||
the associated WRITE operations. | the associated WRITE operations. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | ||||
</section> | <section numbered="true" toc="default"> | |||
<name>pNFS Mechanics</name> | ||||
<section title="pNFS Mechanics"> | <t> | |||
<t> | ||||
This section describes the operations flow taken by a pNFS client | This section describes the operations flow taken by a pNFS client | |||
to a metadata server and storage device. | to a metadata server and storage device. | |||
</t> | </t> | |||
<t> | <t> | |||
When a pNFS client encounters a new FSID, it sends a GETATTR to the | When a pNFS client encounters a new FSID, it sends a GETATTR to the | |||
NFSv4.1 server for the fs_layout_type (<xref target="attrdef_fs_layout_type" | NFSv4.1 server for the fs_layout_type (<xref target="attrdef_fs_layout_type" f | |||
/>) attribute. If the attribute returns at least one layout type, | ormat="default"/>) attribute. If the attribute returns at least one layout type, | |||
and the layout types returned are among the set supported by | and the layout types returned are among the set supported by | |||
the client, the client knows that pNFS is a possibility for the file | the client, the client knows that pNFS is a possibility for the file | |||
system. If, from the server that returned the new FSID, the client | system. If, from the server that returned the new FSID, the client | |||
does not have a client ID that came from an EXCHANGE_ID result that | does not have a client ID that came from an EXCHANGE_ID result that | |||
returned EXCHGID4_FLAG_USE_PNFS_MDS, it MUST send an EXCHANGE_ID to | returned EXCHGID4_FLAG_USE_PNFS_MDS, it <bcp14>MUST</bcp14> send an EXCHANGE_I D to | |||
the server with the EXCHGID4_FLAG_USE_PNFS_MDS bit set. If the | the server with the EXCHGID4_FLAG_USE_PNFS_MDS bit set. If the | |||
server's response does not have EXCHGID4_FLAG_USE_PNFS_MDS, then | server's response does not have EXCHGID4_FLAG_USE_PNFS_MDS, then | |||
contrary to what the fs_layout_type attribute said, the server does | contrary to what the fs_layout_type attribute said, the server does | |||
not support pNFS, and the client will not be able use pNFS to that | not support pNFS, and the client will not be able use pNFS to that | |||
server; in this case, the server MUST return NFS4ERR_NOTSUPP in | server; in this case, the server <bcp14>MUST</bcp14> return NFS4ERR_NOTSUPP in | |||
response to any pNFS operation. | response to any pNFS operation. | |||
</t> | </t> | |||
<t> | <t> | |||
The client then creates a session, requesting a persistent session, so | The client then creates a session, requesting a persistent session, so | |||
that exclusive creates can be done with single round trip via the | that exclusive creates can be done with single round trip via the | |||
createmode4 of GUARDED4. If the session ends up not being persistent, | createmode4 of GUARDED4. If the session ends up not being persistent, | |||
the client will use EXCLUSIVE4_1 for exclusive creates. | the client will use EXCLUSIVE4_1 for exclusive creates. | |||
</t> | </t> | |||
<t> | <t> | |||
If a file is to be created on a pNFS-enabled file | If a file is to be created on a pNFS-enabled file | |||
system, the client uses the OPEN operation. With the | system, the client uses the OPEN operation. With the | |||
normal set of attributes that may be provided upon OPEN | normal set of attributes that may be provided upon OPEN | |||
used for creation, there is an OPTIONAL layout_hint | used for creation, there is an <bcp14>OPTIONAL</bcp14> layout_hint | |||
attribute. The client's use of layout_hint allows the | attribute. The client's use of layout_hint allows the | |||
client to express its preference for a layout type and its | client to express its preference for a layout type and its | |||
associated layout details. The use of a createmode4 of | associated layout details. The use of a createmode4 of | |||
UNCHECKED4, GUARDED4, or EXCLUSIVE4_1 will allow the | UNCHECKED4, GUARDED4, or EXCLUSIVE4_1 will allow the | |||
client to provide the layout_hint attribute at create | client to provide the layout_hint attribute at create | |||
time. The client MUST NOT use EXCLUSIVE4 (see <xref | time. The client <bcp14>MUST NOT</bcp14> use EXCLUSIVE4 (see <xref target="exc | |||
target="exclusive_create"/>). The client is RECOMMENDED | lusive_create" format="default"/>). The client is <bcp14>RECOMMENDED</bcp14> | |||
to combine a GETATTR operation after the OPEN within | to combine a GETATTR operation after the OPEN within | |||
the same COMPOUND. The GETATTR may then retrieve | the same COMPOUND. The GETATTR may then retrieve | |||
the layout_type attribute for the newly created file. | the layout_type attribute for the newly created file. | |||
The client will then know what layout type the server has | The client will then know what layout type the server has | |||
chosen for the file and therefore what storage protocol | chosen for the file and therefore what storage protocol | |||
the client must use. | the client must use. | |||
</t> | </t> | |||
<t> | <t> | |||
If the client wants to open an existing file, then it also includes | If the client wants to open an existing file, then it also includes | |||
a GETATTR to determine what layout type the file supports. | a GETATTR to determine what layout type the file supports. | |||
</t> | </t> | |||
<t> | <t> | |||
The GETATTR in either the file creation or plain file open case can | The GETATTR in either the file creation or plain file open case can | |||
also include the layout_blksize and layout_alignment attributes so | also include the layout_blksize and layout_alignment attributes so | |||
that the client can determine optimal offsets and lengths for I/O on | that the client can determine optimal offsets and lengths for I/O on | |||
the file. | the file. | |||
</t> | </t> | |||
<t> | <t> | |||
Assuming the client supports the layout type returned by GETATTR and | Assuming the client supports the layout type returned by GETATTR and | |||
it chooses to use pNFS for data access, it then sends LAYOUTGET | it chooses to use pNFS for data access, it then sends LAYOUTGET | |||
using the filehandle and stateid returned by OPEN, specifying the range it wan ts | using the filehandle and stateid returned by OPEN, specifying the range it wan ts | |||
to do I/O on. The response is a layout, which may be a subset of the | to do I/O on. The response is a layout, which may be a subset of the | |||
range for which the client asked. It also includes device IDs and a | range for which the client asked. It also includes device IDs and a | |||
description of how data is organized (or in the case of writing, how | description of how data is organized (or in the case of writing, how | |||
data is to be organized) across the devices. The device IDs and | data is to be organized) across the devices. The device IDs and | |||
data description are encoded in a format that is specific to the | data description are encoded in a format that is specific to the | |||
layout type, but the client is expected to understand. | layout type, but the client is expected to understand. | |||
</t> | </t> | |||
<t> | <t> | |||
When the client wants to send an I/O, it determines to which device ID | When the client wants to send an I/O, it determines to which device ID | |||
it needs to send the I/O command by examining the data | it needs to send the I/O command by examining the data | |||
description in the layout. It then sends a | description in the layout. It then sends a | |||
GETDEVICEINFO to find the device address(es) of the device ID. The | GETDEVICEINFO to find the device address(es) of the device ID. The | |||
client then sends the I/O request to one of device ID's device addresses, usin g the | client then sends the I/O request to one of device ID's device addresses, usin g the | |||
storage protocol defined for the layout type. | storage protocol defined for the layout type. | |||
Note that if a client has multiple I/Os to send, | Note that if a client has multiple I/Os to send, | |||
these I/O requests may be done in parallel. | these I/O requests may be done in parallel. | |||
</t> | </t> | |||
<t> | <t> | |||
If the I/O was a WRITE, then at some point | If the I/O was a WRITE, then at some point | |||
the client may want to use LAYOUTCOMMIT to | the client may want to use LAYOUTCOMMIT to | |||
commit the modification time and the new size | commit the modification time and the new size | |||
of the file (if it believes it extended the file size) to the | of the file (if it believes it extended the file size) to the | |||
metadata server and the modified data to the file system. | metadata server and the modified data to the file system. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Recovery" anchor="crash_recovery"> | <section anchor="crash_recovery" numbered="true" toc="default"> | |||
<t> | <name>Recovery</name> | |||
<t> | ||||
Recovery is complicated by the distributed nature of the pNFS | Recovery is complicated by the distributed nature of the pNFS | |||
protocol. In general, crash recovery for layouts is similar to | protocol. In general, crash recovery for layouts is similar to | |||
crash recovery for delegations in the base NFSv4.1 protocol. However, | crash recovery for delegations in the base NFSv4.1 protocol. However, | |||
the client's ability to perform I/O without contacting the metadata | the client's ability to perform I/O without contacting the metadata | |||
server introduces subtleties that must be handled correctly if | server introduces subtleties that must be handled correctly if | |||
the possibility of file system corruption is to be avoided. | the possibility of file system corruption is to be avoided. | |||
</t> | </t> | |||
<section title="Recovery from Client Restart" anchor="pnfs_client_recovery"> | <section anchor="pnfs_client_recovery" numbered="true" toc="default"> | |||
<t> | <name>Recovery from Client Restart</name> | |||
<t> | ||||
Client recovery for layouts is similar to client recovery for other | Client recovery for layouts is similar to client recovery for other | |||
lock and delegation state. When a pNFS client restarts, it will lose | lock and delegation state. When a pNFS client restarts, it will lose | |||
all information about the layouts that it previously owned. There | all information about the layouts that it previously owned. There | |||
are two methods by which the server can reclaim these resources and | are two methods by which the server can reclaim these resources and | |||
allow otherwise conflicting layouts to be provided to other | allow otherwise conflicting layouts to be provided to other | |||
clients. | clients. | |||
</t> | </t> | |||
<t> | <t> | |||
The first is through the expiry of the client's lease. If the | The first is through the expiry of the client's lease. If the | |||
client recovery time is longer than the lease period, the client's | client recovery time is longer than the lease period, the client's | |||
lease will expire and the server will know that state may be | lease will expire and the server will know that state may be | |||
released. For layouts, the server may release the state immediately | released. For layouts, the server may release the state immediately | |||
upon lease expiry or it may allow the layout to persist, awaiting | upon lease expiry or it may allow the layout to persist, awaiting | |||
possible lease revival, as long as no other layout conflicts. | possible lease revival, as long as no other layout conflicts. | |||
</t> | </t> | |||
<t> | <t> | |||
The second is through the client restarting in less time than it | The second is through the client restarting in less time than it | |||
takes for the lease period to expire. In such a case, the client | takes for the lease period to expire. In such a case, the client | |||
will contact the server through the standard EXCHANGE_ID protocol. | will contact the server through the standard EXCHANGE_ID protocol. | |||
The server will find that the client's co_ownerid matches the | The server will find that the client's co_ownerid matches the | |||
co_ownerid of the previous client invocation, but that the verifier | co_ownerid of the previous client invocation, but that the verifier | |||
is different. The server uses this as a signal to release all | is different. The server uses this as a signal to release all | |||
layout state associated with the client's previous invocation. In | layout state associated with the client's previous invocation. In | |||
this scenario, the data written by the client but not covered by a | this scenario, the data written by the client but not covered by a | |||
successful LAYOUTCOMMIT is in an undefined state; it may have been | successful LAYOUTCOMMIT is in an undefined state; it may have been | |||
written or it may now be lost. This is acceptable behavior and it | written or it may now be lost. This is acceptable behavior and it | |||
is the client's responsibility to use LAYOUTCOMMIT to achieve the | is the client's responsibility to use LAYOUTCOMMIT to achieve the | |||
desired level of stability. | desired level of stability. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="lease_expiration_client" numbered="true" toc="default"> | ||||
<section title="Dealing with Lease Expiration on the Client" | <name>Dealing with Lease Expiration on the Client</name> | |||
anchor="lease_expiration_client"> | <t anchor="pnfs_clnt_case1"> | |||
<t anchor="pnfs_clnt_case1"> | If a client believes its lease has expired, it <bcp14>MUST NOT</bcp14> send I | |||
If a client believes its lease has expired, it MUST NOT send I/O | /O | |||
to the storage device until it has validated its lease. The client | to the storage device until it has validated its lease. The client | |||
can send a SEQUENCE operation to the metadata server. If the | can send a SEQUENCE operation to the metadata server. If the | |||
SEQUENCE operation is successful, but sr_status_flag has | SEQUENCE operation is successful, but sr_status_flag has | |||
SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED, | SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED, | |||
SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED, or | SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED, or | |||
SEQ4_STATUS_ADMIN_STATE_REVOKED set, the client MUST NOT use | SEQ4_STATUS_ADMIN_STATE_REVOKED set, the client <bcp14>MUST NOT</bcp14> use | |||
currently held layouts. The client has two | currently held layouts. The client has two | |||
choices to recover from the lease expiration. First, for all | choices to recover from the lease expiration. First, for all | |||
modified but uncommitted data, the client writes it to the metadata server | modified but uncommitted data, the client writes it to the metadata server | |||
using the FILE_SYNC4 flag for the WRITEs, or WRITE and | using the FILE_SYNC4 flag for the WRITEs, or WRITE and | |||
COMMIT. Second, the client re-establishes a client ID and session with | COMMIT. Second, the client re-establishes a client ID and session with | |||
the server and obtains new layouts and device-ID-to-device-address | the server and obtains new layouts and device-ID-to-device-address | |||
mappings for the modified data ranges and then writes the data to the | mappings for the modified data ranges and then writes the data to the | |||
storage devices with the newly obtained layouts. | storage devices with the newly obtained layouts. | |||
</t> | </t> | |||
<t anchor="pnfs_clnt_case2"> | <t anchor="pnfs_clnt_case2"> | |||
If sr_status_flags from the metadata server has | If sr_status_flags from the metadata server has | |||
SEQ4_STATUS_RESTART_RECLAIM_NEEDED set | SEQ4_STATUS_RESTART_RECLAIM_NEEDED set | |||
(or SEQUENCE returns NFS4ERR_BAD_SESSION and | (or SEQUENCE returns NFS4ERR_BAD_SESSION and | |||
CREATE_SESSION returns NFS4ERR_STALE_CLIENTID), then the metadata | CREATE_SESSION returns NFS4ERR_STALE_CLIENTID), then the metadata | |||
server has restarted, and the client SHOULD recover using the | server has restarted, and the client <bcp14>SHOULD</bcp14> recover using the | |||
methods described in <xref target="mds_recovery" />. | methods described in <xref target="mds_recovery" format="default"/>. | |||
</t> | </t> | |||
<t anchor="pnfs_clnt_case3"> | <t anchor="pnfs_clnt_case3"> | |||
If sr_status_flags from the metadata server has | If sr_status_flags from the metadata server has | |||
SEQ4_STATUS_LEASE_MOVED set, then the client recovers by following | SEQ4_STATUS_LEASE_MOVED set, then the client recovers by following | |||
the procedure described in <xref | the procedure described in <xref target="transferred_lease" format="default"/ | |||
target="transferred_lease"/>. After that, the client may get an | >. After that, the client may get an | |||
indication that the layout state was not moved with the file | indication that the layout state was not moved with the file | |||
system. The client recovers as in the other | system. The client recovers as in the other | |||
applicable situations discussed in the first two paragraphs of this section. | applicable situations discussed in the first two paragraphs of this section. | |||
</t> | </t> | |||
<t anchor="pnfs_clnt_case4"> | <t anchor="pnfs_clnt_case4"> | |||
If sr_status_flags reports no loss of state, then the lease for the | If sr_status_flags reports no loss of state, then the lease for the | |||
layouts that the client has are valid and | layouts that the client has are valid and | |||
renewed, and the client can once again send I/O requests to the | renewed, and the client can once again send I/O requests to the | |||
storage devices. | storage devices. | |||
</t> | </t> | |||
<t> | <t> | |||
While clients SHOULD NOT send I/Os to storage devices that may | While clients <bcp14>SHOULD NOT</bcp14> send I/Os to storage devices that may | |||
extend past the lease expiration time period, this is not always | extend past the lease expiration time period, this is not always | |||
possible, for example, an extended network partition that starts | possible, for example, an extended network partition that starts | |||
after the I/O is sent and does not heal until the I/O request is | after the I/O is sent and does not heal until the I/O request is | |||
received by the storage device. Thus, the metadata server and/or | received by the storage device. Thus, the metadata server and/or | |||
storage devices are responsible for protecting themselves from I/Os | storage devices are responsible for protecting themselves from I/Os | |||
that are both sent before the lease expires and arrive after the lease | that are both sent before the lease expires and arrive after the lease | |||
expires. See <xref target="lease_expiration_mds" />. | expires. See <xref target="lease_expiration_mds" format="default"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="lease_expiration_mds" numbered="true" toc="default"> | ||||
<section title="Dealing with Loss of Layout State on the Metadata Server" | <name>Dealing with Loss of Layout State on the Metadata Server</name> | |||
anchor="lease_expiration_mds"> | <t> | |||
<t> | ||||
This is a description of the case where all of the following are | This is a description of the case where all of the following are | |||
true: | true: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
the metadata server has not restarted | the metadata server has not restarted | |||
</t> | </li> | |||
<t> | <li> | |||
a pNFS client's | a pNFS client's | |||
layouts have been discarded (usually because the client's lease | layouts have been discarded (usually because the client's lease | |||
expired) and are invalid | expired) and are invalid | |||
</t> | </li> | |||
<t> | <li> | |||
an I/O from the pNFS client arrives at the storage device | an I/O from the pNFS client arrives at the storage device | |||
</t> | </li> | |||
</list> | </ul> | |||
The metadata server and its storage devices MUST solve this by | <t> | |||
fencing the client. In other words, they MUST solve this by | The metadata server and its storage devices <bcp14>MUST</bcp14> solve this by | |||
fencing the client. In other words, they <bcp14>MUST</bcp14> solve this by | ||||
preventing the execution of I/O operations from the client to the | preventing the execution of I/O operations from the client to the | |||
storage devices after layout | storage devices after layout | |||
state loss. The details of how fencing is done are specific to the | state loss. The details of how fencing is done are specific to the | |||
layout type. The solution for NFSv4.1 file-based layouts is | layout type. The solution for NFSv4.1 file-based layouts is | |||
described in (<xref target="file_layout_revoke" />), and solutions for other | described in (<xref target="file_layout_revoke" format="default"/>), and solu tions for other | |||
layout types are in their respective external specification documents. | layout types are in their respective external specification documents. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="mds_recovery" numbered="true" toc="default"> | ||||
<section title="Recovery from Metadata Server Restart" anchor="mds_recovery"> | <name>Recovery from Metadata Server Restart</name> | |||
<t> | <t> | |||
The pNFS client will discover that the metadata server has | The pNFS client will discover that the metadata server has | |||
restarted via the methods described in <xref | restarted via the methods described in <xref target="server_failure" format= | |||
target="server_failure" /> and discussed in a pNFS-specific | "default"/> and discussed in a pNFS-specific | |||
context in <xref target="pnfs_clnt_case2" />. The client MUST stop using | context in <xref target="pnfs_clnt_case2" format="default"/>. The client <b | |||
cp14>MUST</bcp14> stop using | ||||
layouts and delete the device ID to device address mappings it | layouts and delete the device ID to device address mappings it | |||
previously received from the metadata server. Having done that, | previously received from the metadata server. Having done that, | |||
if the client wrote data to the storage device without committing | if the client wrote data to the storage device without committing | |||
the layouts via LAYOUTCOMMIT, then the client has | the layouts via LAYOUTCOMMIT, then the client has | |||
additional work to do in order to have the client, metadata server, | additional work to do in order to have the client, metadata server, | |||
and storage device(s) all synchronized on the state of the data. | and storage device(s) all synchronized on the state of the data. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
If the client has data still modified | If the client has data still modified | |||
and unwritten in the client's memory, the client has only two choices. | and unwritten in the client's memory, the client has only two choices. | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
The client can obtain a layout via LAYOUTGET after the | The client can obtain a layout via LAYOUTGET after the | |||
server's grace period and write the data to the storage devices. | server's grace period and write the data to the storage devices. | |||
</t> | </li> | |||
<t> | <li> | |||
The client can WRITE that data through the metadata server using the | The client can WRITE that data through the metadata server using the | |||
WRITE (<xref target="OP_WRITE" />) operation, and then obtain | WRITE (<xref target="OP_WRITE" format="default"/>) operation, and then obta in | |||
layouts as desired. | layouts as desired. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | </li> | |||
<t> | <li> | |||
If the client asynchronously wrote data to the storage device, but | If the client asynchronously wrote data to the storage device, but | |||
still has a copy of the data in its memory, then it has available | still has a copy of the data in its memory, then it has available | |||
to it the recovery options listed above in the previous bullet | to it the recovery options listed above in the previous bullet | |||
point. If the metadata server is also in its grace period, the | point. If the metadata server is also in its grace period, the | |||
client has available to it the options below in the next bullet | client has available to it the options below in the next bullet | |||
point. | point. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
The client does not have a copy of the data in its memory and the | The client does not have a copy of the data in its memory and the | |||
metadata server is still in its grace period. The client cannot | metadata server is still in its grace period. The client cannot | |||
use LAYOUTGET (within or outside the grace period) to reclaim a | use LAYOUTGET (within or outside the grace period) to reclaim a | |||
layout because the contents of the response from LAYOUTGET | layout because the contents of the response from LAYOUTGET | |||
may not match what it had previously. The range might be | may not match what it had previously. The range might be | |||
different or the client might get the same range but the content of the | different or the client might get the same range but the content of the | |||
layout might be different. Even if the content of the layout | layout might be different. Even if the content of the layout | |||
appears to be the same, the device IDs may map to different | appears to be the same, the device IDs may map to different | |||
device addresses, and even if the device addresses are the same, | device addresses, and even if the device addresses are the same, | |||
the device addresses could have been assigned to a different | the device addresses could have been assigned to a different | |||
storage device. The option of retrieving the data from the | storage device. The option of retrieving the data from the | |||
storage device and writing it to the metadata server per the | storage device and writing it to the metadata server per the | |||
recovery scenario described above is | recovery scenario described above is | |||
not available because, again, the mappings of range to device ID, | not available because, again, the mappings of range to device ID, | |||
device ID to device address, and device address to physical device are | device ID to device address, and device address to physical device are | |||
stale, and new mappings via new LAYOUTGET do not solve the problem. | stale, and new mappings via new LAYOUTGET do not solve the problem. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
The only recovery option for this scenario is to send a | The only recovery option for this scenario is to send a | |||
LAYOUTCOMMIT in reclaim mode, which the metadata server will | LAYOUTCOMMIT in reclaim mode, which the metadata server will | |||
accept as long as it is in its grace period. The use of | accept as long as it is in its grace period. The use of | |||
LAYOUTCOMMIT in reclaim mode informs the metadata server that the | LAYOUTCOMMIT in reclaim mode informs the metadata server that the | |||
layout has changed. It is critical that the metadata server | layout has changed. It is critical that the metadata server | |||
receive this information before its grace period ends, and thus | receive this information before its grace period ends, and thus | |||
before it starts allowing updates to the file system. | before it starts allowing updates to the file system. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
To send LAYOUTCOMMIT in reclaim mode, the client sets the | To send LAYOUTCOMMIT in reclaim mode, the client sets the | |||
loca_reclaim field of the operation's arguments (<xref | loca_reclaim field of the operation's arguments (<xref target="OP_LAYOUTCOMM | |||
target="OP_LAYOUTCOMMIT_ARGUMENT"/>) to TRUE. During the metadata | IT_ARGUMENT" format="default"/>) to TRUE. During the metadata | |||
server's recovery grace period (and only during the recovery grace | server's recovery grace period (and only during the recovery grace | |||
period) the metadata server is prepared to accept LAYOUTCOMMIT | period) the metadata server is prepared to accept LAYOUTCOMMIT | |||
requests with the loca_reclaim field set to TRUE. | requests with the loca_reclaim field set to TRUE. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
When loca_reclaim is TRUE, the client is attempting to commit | When loca_reclaim is TRUE, the client is attempting to commit | |||
changes to the layout that occurred prior to the restart | changes to the layout that occurred prior to the restart | |||
of the metadata server. The metadata server applies some | of the metadata server. The metadata server applies some | |||
consistency checks on the loca_layoutupdate field of the arguments | consistency checks on the loca_layoutupdate field of the arguments | |||
to determine whether the client can commit the data written to the | to determine whether the client can commit the data written to the | |||
storage device to the file system. The loca_layoutupdate field is of | storage device to the file system. The loca_layoutupdate field is of | |||
data type layoutupdate4 and contains layout-type-specific content | data type layoutupdate4 and contains layout-type-specific content | |||
(in the lou_body field of loca_layoutupdate). The | (in the lou_body field of loca_layoutupdate). The | |||
layout-type-specific information that loca_layoutupdate might have | layout-type-specific information that loca_layoutupdate might have | |||
is discussed in <xref target="layoutcommit_update" />. If the | is discussed in <xref target="layoutcommit_update" format="default"/>. If t he | |||
metadata server's consistency checks on loca_layoutupdate succeed, | metadata server's consistency checks on loca_layoutupdate succeed, | |||
then the metadata server MUST commit the data (as described by the | then the metadata server <bcp14>MUST</bcp14> commit the data (as described b y the | |||
loca_offset, loca_length, and loca_layoutupdate fields of the | loca_offset, loca_length, and loca_layoutupdate fields of the | |||
arguments) that was written to the storage device. If the metadata | arguments) that was written to the storage device. If the metadata | |||
server's consistency checks on loca_layoutupdate fail, the | server's consistency checks on loca_layoutupdate fail, the | |||
metadata server rejects the LAYOUTCOMMIT operation and makes no | metadata server rejects the LAYOUTCOMMIT operation and makes no | |||
changes to the file system. However, any time LAYOUTCOMMIT with | changes to the file system. However, any time LAYOUTCOMMIT with | |||
loca_reclaim TRUE fails, the pNFS client has lost all the data in | loca_reclaim TRUE fails, the pNFS client has lost all the data in | |||
the range defined by <loca_offset, loca_length>. A client | the range defined by <loca_offset, loca_length>. A client | |||
can defend against this risk by caching all data, whether written | can defend against this risk by caching all data, whether written | |||
synchronously or asynchronously in its memory, and by not releasing the | synchronously or asynchronously in its memory, and by not releasing the | |||
cached data until a successful LAYOUTCOMMIT. This condition | cached data until a successful LAYOUTCOMMIT. This condition | |||
does not hold true for all layout types; for example, file-based | does not hold true for all layout types; for example, file-based | |||
storage devices need not suffer from this limitation. | storage devices need not suffer from this limitation. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
The client does not have a copy of the data in its memory and the | The client does not have a copy of the data in its memory and the | |||
metadata server is no longer in its grace period; i.e., the metadata | metadata server is no longer in its grace period; i.e., the metadata | |||
server returns NFS4ERR_NO_GRACE. As with the scenario in the above | server returns NFS4ERR_NO_GRACE. As with the scenario in the above | |||
bullet point, the failure of LAYOUTCOMMIT means the data | bullet point, the failure of LAYOUTCOMMIT means the data | |||
in the range <loca_offset, loca_length> lost. The | in the range <loca_offset, loca_length> lost. The | |||
defense against the risk is the same -- cache all written data | defense against the risk is the same -- cache all written data | |||
on the client until a successful LAYOUTCOMMIT. | on the client until a successful LAYOUTCOMMIT. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section anchor="pnfs_grace_exception" numbered="true" toc="default"> | |||
<section title="Operations during Metadata Server Grace Period" | <name>Operations during Metadata Server Grace Period</name> | |||
anchor="pnfs_grace_exception"> | <t> | |||
<t> | ||||
Some of the recovery scenarios thus far noted that some | Some of the recovery scenarios thus far noted that some | |||
operations (namely, WRITE and LAYOUTGET) might be permitted during | operations (namely, WRITE and LAYOUTGET) might be permitted during | |||
the metadata server's grace period. The metadata server may allow | the metadata server's grace period. The metadata server may allow | |||
these operations during its grace period. For LAYOUTGET, the | these operations during its grace period. For LAYOUTGET, the | |||
metadata server must reliably determine that servicing such a | metadata server must reliably determine that servicing such a | |||
request will not conflict with an impending LAYOUTCOMMIT reclaim | request will not conflict with an impending LAYOUTCOMMIT reclaim | |||
request. For WRITE, the metadata server | request. For WRITE, the metadata server | |||
must reliably determine that servicing the request | must reliably determine that servicing the request | |||
will not conflict with an impending OPEN or with a LOCK where the | will not conflict with an impending OPEN or with a LOCK where the | |||
file has mandatory byte-range locking enabled. | file has mandatory byte-range locking enabled. | |||
</t> | </t> | |||
<t> | <t> | |||
As mentioned previously, for expediency, | As mentioned previously, for expediency, | |||
the metadata server might reject some | the metadata server might reject some | |||
operations (namely, WRITE and LAYOUTGET) during its | operations (namely, WRITE and LAYOUTGET) during its | |||
grace period, because the simplest correct approach | grace period, because the simplest correct approach | |||
is to reject all non-reclaim pNFS requests and WRITE operations by | is to reject all non-reclaim pNFS requests and WRITE operations by | |||
returning the NFS4ERR_GRACE error. However, depending on the | returning the NFS4ERR_GRACE error. However, depending on the | |||
storage protocol (which is specific to the layout type) and | storage protocol (which is specific to the layout type) and | |||
metadata server implementation, the metadata server may be able to | metadata server implementation, the metadata server may be able to | |||
determine that a particular request is safe. For example, a | determine that a particular request is safe. For example, a | |||
metadata server may save provisional allocation mappings for each | metadata server may save provisional allocation mappings for each | |||
file to stable storage, as well as information about potentially | file to stable storage, as well as information about potentially | |||
conflicting OPEN share modes and mandatory byte-range locks that might | conflicting OPEN share modes and mandatory byte-range locks that might | |||
have been in effect at the time of restart, and the metadata | have been in effect at the time of restart, and the metadata | |||
server may use this information during the recovery grace period to determin e that a | server may use this information during the recovery grace period to determin e that a | |||
WRITE request is safe. | WRITE request is safe. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="storage_device_recovery" numbered="true" toc="default"> | ||||
<section anchor="storage_device_recovery" title="Storage Device Recovery"> | <name>Storage Device Recovery</name> | |||
<t> | <t> | |||
Recovery from storage device restart is mostly dependent upon the layout type | Recovery from storage device restart is mostly dependent upon the layout type | |||
in use. However, there are a few general techniques a client can | in use. However, there are a few general techniques a client can | |||
use if it discovers a storage device has crashed while holding | use if it discovers a storage device has crashed while holding | |||
modified, uncommitted data that was asynchronously written. | modified, uncommitted data that was asynchronously written. | |||
First and foremost, it | First and foremost, it | |||
is important to realize that the client is the only one that has the | is important to realize that the client is the only one that has the | |||
information necessary to recover non-committed data since | information necessary to recover non-committed data since | |||
it holds the modified data and probably nothing else does. Second, | it holds the modified data and probably nothing else does. Second, | |||
the best solution is for the client to err on the side of caution | the best solution is for the client to err on the side of caution | |||
and attempt to rewrite the modified data through another path. | and attempt to rewrite the modified data through another path. | |||
</t> | </t> | |||
<t> | <t> | |||
The client SHOULD immediately WRITE the data to the metadata server, | The client <bcp14>SHOULD</bcp14> immediately WRITE the data to the metadata se | |||
rver, | ||||
with the stable field in the WRITE4args set to FILE_SYNC4. Once it | with the stable field in the WRITE4args set to FILE_SYNC4. Once it | |||
does this, there is no need to wait for the original storage device. | does this, there is no need to wait for the original storage device. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="Metadata and Storage Device Roles"> | <name>Metadata and Storage Device Roles</name> | |||
<t> | <t> | |||
If the same physical hardware is used to implement both a | If the same physical hardware is used to implement both a | |||
metadata server and storage device, then the same hardware | metadata server and storage device, then the same hardware | |||
entity is to be understood to be implementing two | entity is to be understood to be implementing two | |||
distinct roles and it is important that it be clearly | distinct roles and it is important that it be clearly | |||
understood on behalf of which role the hardware is | understood on behalf of which role the hardware is | |||
executing at any given time. | executing at any given time. | |||
</t> | </t> | |||
<t> | <t> | |||
Two sub-cases can be distinguished. | Two sub-cases can be distinguished. | |||
<list style="numbers"> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
The storage device uses NFSv4.1 as the storage protocol, i.e., the same | The storage device uses NFSv4.1 as the storage protocol, i.e., the same | |||
physical hardware is used to implement both a metadata and data | physical hardware is used to implement both a metadata and data | |||
server. See <xref target="pnfs_session_stuff" /> | server. See <xref target="pnfs_session_stuff" format="default"/> | |||
for a description of how multiple roles are handled. | for a description of how multiple roles are handled. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
The storage device does not use NFSv4.1 as the storage protocol, | The storage device does not use NFSv4.1 as the storage protocol, | |||
and the same physical hardware is used to implement both a | and the same physical hardware is used to implement both a | |||
metadata and storage device. Whether distinct network addresses | metadata and storage device. Whether distinct network addresses | |||
are used to access the metadata server and storage device is | are used to access the metadata server and storage device is | |||
immaterial. This is because it is always clear to the pNFS client and | immaterial. This is because it is always clear to the pNFS client and | |||
server, from the upper-layer protocol being used (NFSv4.1 or | server, from the upper-layer protocol being used (NFSv4.1 or | |||
non-NFSv4.1), to which role the request to the common server network | non-NFSv4.1), to which role the request to the common server network | |||
address is directed. | address is directed. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | </section> | |||
</section> | <section anchor="security_considerations_pnfs" numbered="true" toc="defaul | |||
t"> | ||||
<section title="Security Considerations for pNFS" anchor="security_consideration | <name>Security Considerations for pNFS</name> | |||
s_pnfs"> | <t> | |||
<t> | ||||
pNFS separates file system metadata and data and provides access to | pNFS separates file system metadata and data and provides access to | |||
both. There are pNFS-specific operations (listed in | both. There are pNFS-specific operations (listed in | |||
<xref target="pnfs_ops" />) that provide access to the metadata; all | <xref target="pnfs_ops" format="default"/>) that provide access to the metadat a; all | |||
existing NFSv4.1 conventional (non-pNFS) security mechanisms and | existing NFSv4.1 conventional (non-pNFS) security mechanisms and | |||
features apply to accessing the metadata. The combination of | features apply to accessing the metadata. The combination of | |||
components in a pNFS system (see <xref target="fig_system" />) is | components in a pNFS system (see <xref target="fig_system" format="default"/>) is | |||
required to preserve the security properties of NFSv4.1 with respect | required to preserve the security properties of NFSv4.1 with respect | |||
to an entity that is accessing a storage device from a client, including | to an entity that is accessing a storage device from a client, including | |||
security countermeasures to defend against threats for which NFSv4.1 | security countermeasures to defend against threats for which NFSv4.1 | |||
provides defenses in environments where these threats are | provides defenses in environments where these threats are | |||
considered significant. | considered significant. | |||
</t> | </t> | |||
<t> | <t> | |||
In some cases, the security countermeasures for connections | In some cases, the security countermeasures for connections | |||
to storage devices may take the form of physical isolation or a | to storage devices may take the form of physical isolation or a | |||
recommendation to avoid the use of pNFS in an environment. For example, it | recommendation to avoid the use of pNFS in an environment. For example, it | |||
may be impractical to provide confidentiality protection for some | may be impractical to provide confidentiality protection for some | |||
storage protocols to protect against eavesdropping. In | storage protocols to protect against eavesdropping. In | |||
environments where eavesdropping on such protocols is of sufficient | environments where eavesdropping on such protocols is of sufficient | |||
concern to require countermeasures, physical isolation of the | concern to require countermeasures, physical isolation of the | |||
communication channel (e.g., via direct connection from client(s) | communication channel (e.g., via direct connection from client(s) | |||
to storage device(s)) and/or a decision to forgo use of pNFS (e.g., | to storage device(s)) and/or a decision to forgo use of pNFS (e.g., | |||
and fall back to conventional NFSv4.1) may be appropriate courses of action. | and fall back to conventional NFSv4.1) may be appropriate courses of action. | |||
</t> | </t> | |||
<t> | <t> | |||
Where communication with storage devices is subject to the same | Where communication with storage devices is subject to the same | |||
threats as client-to-metadata server communication, the protocols | threats as client-to-metadata server communication, the protocols | |||
used for that communication need to provide security mechanisms as | used for that communication need to provide security mechanisms as | |||
strong as or no weaker than those available via RPCSEC_GSS for | strong as or no weaker than those available via RPCSEC_GSS for | |||
NFSv4.1. Except for the storage protocol used for the LAYOUT4_NFSV4_1_FILES | NFSv4.1. Except for the storage protocol used for the LAYOUT4_NFSV4_1_FILES | |||
layout (see <xref target="file_layout_type"/>), i.e., except for NFSv4.1, | layout (see <xref target="file_layout_type" format="default"/>), i.e., except for NFSv4.1, | |||
it is beyond the scope of this document to specify the security mechanisms | it is beyond the scope of this document to specify the security mechanisms | |||
for storage access protocols. | for storage access protocols. | |||
</t> | </t> | |||
<t> | <t> | |||
pNFS implementations MUST NOT remove NFSv4.1's access controls. | pNFS implementations <bcp14>MUST NOT</bcp14> remove NFSv4.1's access controls. | |||
The combination of clients, storage devices, and the metadata server | The combination of clients, storage devices, and the metadata server | |||
are responsible for ensuring that all client-to-storage-device file | are responsible for ensuring that all client-to-storage-device file | |||
data access respects NFSv4.1's ACLs and file open modes. This entails | data access respects NFSv4.1's ACLs and file open modes. This entails | |||
performing both of these checks on every access in the client, the | performing both of these checks on every access in the client, the | |||
storage device, or both (as applicable; when the storage device is | storage device, or both (as applicable; when the storage device is | |||
an NFSv4.1 server, the storage device is ultimately responsible for | an NFSv4.1 server, the storage device is ultimately responsible for | |||
controlling access as described in <xref target="state_propagation"/>). | controlling access as described in <xref target="state_propagation" format="de fault"/>). | |||
If a pNFS configuration performs these checks only in the client, | If a pNFS configuration performs these checks only in the client, | |||
the risk of a misbehaving client obtaining unauthorized access is | the risk of a misbehaving client obtaining unauthorized access is | |||
an important consideration in determining when it is appropriate to | an important consideration in determining when it is appropriate to | |||
use such a pNFS configuration. Such layout types SHOULD NOT be used | use such a pNFS configuration. Such layout types <bcp14>SHOULD NOT</bcp14> be used | |||
when client-only access checks do not provide sufficient assurance | when client-only access checks do not provide sufficient assurance | |||
that NFSv4.1 access control is being applied correctly. (This | that NFSv4.1 access control is being applied correctly. (This | |||
is not a problem for the file layout type described in <xref | is not a problem for the file layout type described in <xref target="file_layo | |||
target="file_layout_type"/> because the storage access protocol for | ut_type" format="default"/> because the storage access protocol for | |||
LAYOUT4_NFSV4_1_FILES is NFSv4.1, and thus the security model for | LAYOUT4_NFSV4_1_FILES is NFSv4.1, and thus the security model for | |||
storage device access via LAYOUT4_NFSv4_1_FILES is the same as that | storage device access via LAYOUT4_NFSv4_1_FILES is the same as that | |||
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">NFSv4.1/file-based layout</xref> | the <xref target="file_layout_type" format="default">NFSv4.1/file-based layout | |||
of this document, the <xref target="RFC5663">blocks | </xref> | |||
layout</xref>, and <xref target="RFC5664">objects | of this document, the <xref target="RFC5663" format="default">blocks | |||
layout</xref>, and <xref target="RFC5664" format="default">objects | ||||
layout</xref>. | layout</xref>. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | ||||
</section> | <section anchor="file_layout_type" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp $ | <name>NFSv4.1 as a Storage Protocol in pNFS: the File Layout Type</name> | |||
--> | <t> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | ||||
<!-- Copyright (C) The Internet Society (2006) --> | ||||
<section title="NFSv4.1 as a Storage Protocol in pNFS: the File Layout Type" anc | ||||
hor="file_layout_type"> | ||||
<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 title="Client ID and Session Considerations" anchor="pnfs_session_stuf | <section anchor="pnfs_session_stuff" numbered="true" toc="default"> | |||
f"> | <name>Client ID and Session Considerations</name> | |||
<t> | <t> | |||
Sessions are a REQUIRED feature of NFSv4.1, and this | Sessions are a <bcp14>REQUIRED</bcp14> feature of NFSv4.1, and this | |||
extends to both the metadata server and file-based (NFSv4.1-based) | extends to both the metadata server and file-based (NFSv4.1-based) | |||
data servers. | data servers. | |||
</t> | </t> | |||
<t> | <t> | |||
The role a server plays in pNFS is determined by the result it returns | The role a server plays in pNFS is determined by the result it returns | |||
from EXCHANGE_ID. | from EXCHANGE_ID. | |||
The roles are: | The roles are: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Metadata server (EXCHGID4_FLAG_USE_PNFS_MDS is set in the result eir_flags). | Metadata server (EXCHGID4_FLAG_USE_PNFS_MDS is set in the result eir_flags). | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
Data server (EXCHGID4_FLAG_USE_PNFS_DS). | Data server (EXCHGID4_FLAG_USE_PNFS_DS). | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
Non-metadata server (EXCHGID4_FLAG_USE_NON_PNFS). This is an NFSv4.1 | Non-metadata server (EXCHGID4_FLAG_USE_NON_PNFS). This is an NFSv4.1 | |||
server that does not support operations (e.g., | server that does not support operations (e.g., | |||
LAYOUTGET) or attributes that pertain to pNFS. | LAYOUTGET) or attributes that pertain to pNFS. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | The client <bcp14>MAY</bcp14> request zero or more of | |||
The client MAY request zero or more of | ||||
EXCHGID4_FLAG_USE_NON_PNFS, | EXCHGID4_FLAG_USE_NON_PNFS, | |||
EXCHGID4_FLAG_USE_PNFS_DS, or | EXCHGID4_FLAG_USE_PNFS_DS, or | |||
EXCHGID4_FLAG_USE_PNFS_MDS, even though some combinations | EXCHGID4_FLAG_USE_PNFS_MDS, even though some combinations | |||
(e.g., EXCHGID4_FLAG_USE_NON_PNFS | EXCHGID4_FLAG_USE_PNFS_MDS) are | (e.g., EXCHGID4_FLAG_USE_NON_PNFS | EXCHGID4_FLAG_USE_PNFS_MDS) are | |||
contradictory. However, the server MUST only return the following | contradictory. However, the server <bcp14>MUST</bcp14> only return the follow ing | |||
acceptable combinations: | acceptable combinations: | |||
</t> | </t> | |||
<table align="center"> | ||||
<texttable> | <thead> | |||
<tr> | ||||
<ttcol>Acceptable Results from EXCHANGE_ID</ttcol> | <th align="left">Acceptable Results from EXCHANGE_ID</th> | |||
</tr> | ||||
<c> | </thead> | |||
<tbody> | ||||
<tr> | ||||
<td align="left"> | ||||
EXCHGID4_FLAG_USE_PNFS_MDS | EXCHGID4_FLAG_USE_PNFS_MDS | |||
</c> | </td> | |||
</tr> | ||||
<c> | <tr> | |||
<td align="left"> | ||||
EXCHGID4_FLAG_USE_PNFS_MDS | EXCHGID4_FLAG_USE_PNFS_DS | EXCHGID4_FLAG_USE_PNFS_MDS | EXCHGID4_FLAG_USE_PNFS_DS | |||
</c> | </td> | |||
</tr> | ||||
<c> | <tr> | |||
<td align="left"> | ||||
EXCHGID4_FLAG_USE_PNFS_DS | EXCHGID4_FLAG_USE_PNFS_DS | |||
</c> | </td> | |||
</tr> | ||||
<c> | <tr> | |||
<td align="left"> | ||||
EXCHGID4_FLAG_USE_NON_PNFS | EXCHGID4_FLAG_USE_NON_PNFS | |||
</c> | </td> | |||
</tr> | ||||
<c> | <tr> | |||
<td align="left"> | ||||
EXCHGID4_FLAG_USE_PNFS_DS | EXCHGID4_FLAG_USE_NON_PNFS | EXCHGID4_FLAG_USE_PNFS_DS | EXCHGID4_FLAG_USE_NON_PNFS | |||
</c> | </td> | |||
</texttable> | </tr> | |||
<t> | </tbody> | |||
</table> | ||||
<t> | ||||
As the above table implies, a server can have one | As the above table implies, a server can have one | |||
or two roles. A server can be both a metadata server | or two roles. A server can be both a metadata server | |||
and a data server, or it can be both a data server and | and a data server, or it can be both a data server and | |||
non-metadata server. In addition to returning two roles | non-metadata server. In addition to returning two roles | |||
in the EXCHANGE_ID's results, and thus serving both roles | in the EXCHANGE_ID's results, and thus serving both roles | |||
via a common client ID, a server can serve two roles | via a common client ID, a server can serve two roles | |||
by returning a unique client ID and server owner for | by returning a unique client ID and server owner for | |||
each role in each of two EXCHANGE_ID results, with each | each role in each of two EXCHANGE_ID results, with each | |||
result indicating each role. | result indicating each role. | |||
</t> | </t> | |||
<t> | <t> | |||
In the case of a server with concurrent pNFS roles that | In the case of a server with concurrent pNFS roles that | |||
are served by a common client ID, if the EXCHANGE_ID | are served by a common client ID, if the EXCHANGE_ID | |||
request from the client has zero or a combination of the | request from the client has zero or a combination of the | |||
bits set in eia_flags, the server result should set bits | bits set in eia_flags, the server result should set bits | |||
that represent the higher of the acceptable combination | that represent the higher of the acceptable combination | |||
of the server roles, with a preference to match the roles | of the server roles, with a preference to match the roles | |||
requested by the client. Thus, if a client request has | requested by the client. Thus, if a client request has | |||
(EXCHGID4_FLAG_USE_NON_PNFS | EXCHGID4_FLAG_USE_PNFS_MDS | (EXCHGID4_FLAG_USE_NON_PNFS | EXCHGID4_FLAG_USE_PNFS_MDS | |||
| EXCHGID4_FLAG_USE_PNFS_DS) flags set, and the server | | EXCHGID4_FLAG_USE_PNFS_DS) flags set, and the server | |||
is both a metadata server and a data server, serving | is both a metadata server and a data server, serving | |||
both the roles by a common client ID, the server | both the roles by a common client ID, the server | |||
SHOULD return with (EXCHGID4_FLAG_USE_PNFS_MDS | | <bcp14>SHOULD</bcp14> return with (EXCHGID4_FLAG_USE_PNFS_MDS | | |||
EXCHGID4_FLAG_USE_PNFS_DS) set. | EXCHGID4_FLAG_USE_PNFS_DS) set. | |||
</t> | </t> | |||
<t> | <t> | |||
In the case of a server that has multiple concurrent | In the case of a server that has multiple concurrent | |||
pNFS roles, each role served by a unique client ID, | pNFS roles, each role served by a unique client ID, | |||
if the client specifies zero or a combination of roles | if the client specifies zero or a combination of roles | |||
in the request, the server results SHOULD return only | in the request, the server results <bcp14>SHOULD</bcp14> return only | |||
one of the roles from the combination specified by the | one of the roles from the combination specified by the | |||
client request. If the role specified by the server | client request. If the role specified by the server | |||
result does not match the intended use by the client, | result does not match the intended use by the client, | |||
the client should send the EXCHANGE_ID specifying just | the client should send the EXCHANGE_ID specifying just | |||
the interested pNFS role. | the interested pNFS role. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
If a pNFS metadata client gets a layout that refers it to an NFSv4.1 | If a pNFS metadata client gets a layout that refers it to an NFSv4.1 | |||
data server, it needs a client ID on that data server. If it does not | data server, it needs a client ID on that data server. If it does not | |||
yet have a client ID from the server that had the EXCHGID4_FLAG_USE_PNFS_DS | yet have a client ID from the server that had the EXCHGID4_FLAG_USE_PNFS_DS | |||
flag set in the EXCHANGE_ID results, then the client needs to | flag set in the EXCHANGE_ID results, then the client needs to | |||
send an EXCHANGE_ID to the data server, using | send an EXCHANGE_ID to the data server, using | |||
the same co_ownerid as it sent to the metadata server, with the | the same co_ownerid as it sent to the metadata server, with the | |||
EXCHGID4_FLAG_USE_PNFS_DS flag set in the arguments. | EXCHGID4_FLAG_USE_PNFS_DS flag set in the arguments. | |||
If the server's | If the server's | |||
EXCHANGE_ID results have EXCHGID4_FLAG_USE_PNFS_DS set, then the | EXCHANGE_ID results have EXCHGID4_FLAG_USE_PNFS_DS set, then the | |||
client may use the client ID to create sessions that will | client may use the client ID to create sessions that will | |||
exchange pNFS data operations. | exchange pNFS data operations. | |||
The client ID returned by the data server has no relationship with | The client ID returned by the data server has no relationship with | |||
the client ID returned by a metadata server unless the client IDs | the client ID returned by a metadata server unless the client IDs | |||
are equal, and the server owners and server scopes of the data server | are equal, and the server owners and server scopes of the data server | |||
and metadata server are equal. | and metadata server are equal. | |||
</t> | </t> | |||
<t> | <t> | |||
In NFSv4.1, the | In NFSv4.1, the | |||
session ID in the SEQUENCE operation implies the | session ID in the SEQUENCE operation implies the | |||
client ID, which in turn might be used by the server to | client ID, which in turn might be used by the server to | |||
map the stateid to the right client/server pair. | map the stateid to the right client/server pair. | |||
However, when a data server is presented with a READ or | However, when a data server is presented with a READ or | |||
WRITE operation with a stateid, because the | WRITE operation with a stateid, because the | |||
stateid is associated with a | stateid is associated with a | |||
client ID on a metadata server, and because the session ID in | client ID on a metadata server, and because the session ID in | |||
the preceding SEQUENCE operation is tied to the | the preceding SEQUENCE operation is tied to the | |||
client ID of the data server, the data server has no | client ID of the data server, the data server has no | |||
obvious way to determine the metadata server from the | obvious way to determine the metadata server from the | |||
COMPOUND procedure, and thus has no way to validate the | COMPOUND procedure, and thus has no way to validate the | |||
stateid. One RECOMMENDED approach is for pNFS servers to | stateid. One <bcp14>RECOMMENDED</bcp14> approach is for pNFS servers to | |||
encode metadata server routing and/or identity | encode metadata server routing and/or identity | |||
information in the data server filehandles as returned | information in the data server filehandles as returned | |||
in the layout. | in the layout. | |||
</t> | </t> | |||
<t> | <t> | |||
If metadata server routing and/or identity information is encoded | If metadata server routing and/or identity information is encoded | |||
in data server filehandles, | in data server filehandles, | |||
when the metadata server identity or location | when the metadata server identity or location | |||
changes, the data server filehandles it gave out will become | changes, the data server filehandles it gave out will become | |||
invalid (stale), and so the metadata server MUST first | invalid (stale), and so the metadata server <bcp14>MUST</bcp14> first | |||
recall the layouts. | recall the layouts. | |||
Invalidating a data server filehandle does not render | Invalidating a data server filehandle does not render | |||
the NFS client's data cache invalid. The client's cache should | the NFS client's data cache invalid. The client's cache should | |||
map a data server filehandle to a metadata server filehandle, and | map a data server filehandle to a metadata server filehandle, and | |||
a metadata server filehandle to cached data. | a metadata server filehandle to cached data. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
If a server is both a metadata server and a data server, | If a server is both a metadata server and a data server, | |||
the server might need to distinguish operations on | the server might need to distinguish operations on | |||
files that are directed to the metadata server from | files that are directed to the metadata server from | |||
those that are directed to the data server. It is | those that are directed to the data server. It is | |||
RECOMMENDED that the values of the filehandles returned by | <bcp14>RECOMMENDED</bcp14> that the values of the filehandles returned by | |||
the LAYOUTGET operation be different than the value | the LAYOUTGET operation be different than the value | |||
of the filehandle returned by the OPEN of the same file. | of the filehandle returned by the OPEN of the same file. | |||
</t> | </t> | |||
<t> | <t> | |||
Another scenario is for the metadata server and the | Another scenario is for the metadata server and the | |||
storage device to be distinct from one client's point of | storage device to be distinct from one client's point of | |||
view, and the roles reversed from another client's point | view, and the roles reversed from another client's point | |||
of view. For example, in the cluster file system model, | of view. For example, in the cluster file system model, | |||
a metadata server to one client might be a data server to | a metadata server to one client might be a data server to | |||
another client. If NFSv4.1 is being used as the storage | another client. If NFSv4.1 is being used as the storage | |||
protocol, then pNFS servers need to encode the values | protocol, then pNFS servers need to encode the values | |||
of filehandles according to their specific roles. | of filehandles according to their specific roles. | |||
</t> | </t> | |||
<section anchor="dsonly" title="Sessions Considerations for Data Servers"> | <section anchor="dsonly" numbered="true" toc="default"> | |||
<t> | <name>Sessions Considerations for Data Servers</name> | |||
<t> | ||||
<xref target="Obligations_of_the_Client" /> states | <xref target="Obligations_of_the_Client" format="default"/> states | |||
that a client has to keep its lease renewed in | that a client has to keep its lease renewed in | |||
order to prevent a session from being deleted by | order to prevent a session from being deleted by | |||
the server. If the reply to EXCHANGE_ID has just the | the server. If the reply to EXCHANGE_ID has just the | |||
EXCHGID4_FLAG_USE_PNFS_DS role set, then (as noted in | EXCHGID4_FLAG_USE_PNFS_DS role set, then (as noted in | |||
<xref target="ds_ops"/>) the client will not be able | <xref target="ds_ops" format="default"/>) the client will not be able | |||
to determine the data server's lease_time attribute | to determine the data server's lease_time attribute | |||
because GETATTR will not be permitted. Instead, the | because GETATTR will not be permitted. Instead, the | |||
rule is that any time a client receives a layout | rule is that any time a client receives a layout | |||
referring it to a data server that returns just | referring it to a data server that returns just | |||
the EXCHGID4_FLAG_USE_PNFS_DS role, the client MAY | the EXCHGID4_FLAG_USE_PNFS_DS role, the client <bcp14>MAY</bcp14> | |||
assume that the lease_time attribute from the metadata | assume that the lease_time attribute from the metadata | |||
server that returned the layout applies to the data | server that returned the layout applies to the data | |||
server. Thus, the data server MUST be aware of the values | server. Thus, the data server <bcp14>MUST</bcp14> be aware of the values | |||
of all lease_time attributes of all metadata servers for which it | of all lease_time attributes of all metadata servers for which it | |||
is providing I/O, and it MUST use the maximum of all such | is providing I/O, and it <bcp14>MUST</bcp14> use the maximum of all such | |||
lease_time values as the lease interval for all client | lease_time values as the lease interval for all client | |||
IDs and sessions established on it. | IDs and sessions established on it. | |||
</t> | </t> | |||
<t> | <t> | |||
For example, if one metadata server has a lease_time | For example, if one metadata server has a lease_time | |||
attribute of 20 seconds, and a second metadata | attribute of 20 seconds, and a second metadata | |||
server has a lease_time attribute of 10 seconds, | server has a lease_time attribute of 10 seconds, | |||
then if both servers return layouts that refer to an | then if both servers return layouts that refer to an | |||
EXCHGID4_FLAG_USE_PNFS_DS-only data server, the data | EXCHGID4_FLAG_USE_PNFS_DS-only data server, the data | |||
server MUST renew a client's lease if the interval | server <bcp14>MUST</bcp14> renew a client's lease if the interval | |||
between two SEQUENCE operations on different COMPOUND | between two SEQUENCE operations on different COMPOUND | |||
requests is less than 20 seconds. | requests is less than 20 seconds. | |||
</t> | </t> | |||
</section> | ||||
</section> | </section> | |||
<section anchor="file_layout_definitions" numbered="true" toc="default"> | ||||
</section> | <name>File Layout Definitions</name> | |||
<t> | ||||
<section title="File Layout Definitions" anchor="file_layout_definitions"> | ||||
<t> | ||||
The following definitions apply to the LAYOUT4_NFSV4_1_FILES | The following definitions apply to the LAYOUT4_NFSV4_1_FILES | |||
layout type and may be applicable to other layout types. | layout type and may be applicable to other layout types. | |||
<list style='hanging'> | ||||
<t hangText="Unit."> | ||||
A unit is a fixed-size quantity of data written to a data server. | ||||
</t> | </t> | |||
<t hangText="Pattern."> | <dl newline="false" spacing="normal"> | |||
<dt>Unit.</dt> | ||||
<dd> | ||||
A unit is a fixed-size quantity of data written to a data server. | ||||
</dd> | ||||
<dt>Pattern.</dt> | ||||
<dd> | ||||
A pattern is a method of distributing one or more | A pattern is a method of distributing one or more | |||
equal sized units across a set of data servers. | equal sized units across a set of data servers. | |||
A pattern is iterated one or more times. | A pattern is iterated one or more times. | |||
</t> | </dd> | |||
<t hangText="Stripe."> | <dt>Stripe.</dt> | |||
<dd> | ||||
A stripe is a set of data distributed | A stripe is a set of data distributed | |||
across a set of data servers in a | across a set of data servers in a | |||
pattern before that pattern repeats. | pattern before that pattern repeats. | |||
</t> | </dd> | |||
<t hangText="Stripe Count."> | <dt>Stripe Count.</dt> | |||
<dd> | ||||
A stripe count is the number of units in a pattern. | A stripe count is the number of units in a pattern. | |||
</t> | </dd> | |||
<t hangText="Stripe Width."> | <dt>Stripe Width.</dt> | |||
<dd> | ||||
A stripe width is the size of a stripe in bytes. | A stripe width is the size of a stripe in bytes. | |||
The stripe width = the stripe count * the size of the stripe unit. | The stripe width = the stripe count * the size of the stripe unit. | |||
</t> | </dd> | |||
</list> | </dl> | |||
<t> | ||||
Hereafter, this document will refer to a unit that is a written | Hereafter, this document will refer to a unit that is a written | |||
in a pattern as a "stripe unit". | in a pattern as a "stripe unit". | |||
</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 MAY 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> <!-- "File Striping Definitions" "file_layout_definitions" --> | </section> | |||
<section title="File Layout Data Types" anchor="file_data_types"> | <section anchor="file_data_types" numbered="true" toc="default"> | |||
<t> | <name>File Layout Data Types</name> | |||
<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" />). | (<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> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
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; | |||
</artwork> | ||||
</figure> | ||||
<figure> | ||||
<artwork> | ||||
enum filelayout_hint_care4 { | enum filelayout_hint_care4 { | |||
NFLH4_CARE_DENSE = NFL4_UFLG_DENSE, | NFLH4_CARE_DENSE = NFL4_UFLG_DENSE, | |||
NFLH4_CARE_COMMIT_THRU_MDS | NFLH4_CARE_COMMIT_THRU_MDS | |||
= NFL4_UFLG_COMMIT_THRU_MDS, | = NFL4_UFLG_COMMIT_THRU_MDS, | |||
NFLH4_CARE_STRIPE_UNIT_SIZE | NFLH4_CARE_STRIPE_UNIT_SIZE | |||
= 0x00000040, | = 0x00000040, | |||
NFLH4_CARE_STRIPE_COUNT = 0x00000080 | NFLH4_CARE_STRIPE_COUNT = 0x00000080 | |||
}; | }; | |||
/* Encoded in the loh_body field of data type layouthint4: */ | /* Encoded in the loh_body field of data type layouthint4: */ | |||
struct nfsv4_1_file_layouthint4 { | struct nfsv4_1_file_layouthint4 { | |||
uint32_t nflh_care; | uint32_t nflh_care; | |||
nfl_util4 nflh_util; | nfl_util4 nflh_util; | |||
count4 nflh_stripe_count; | count4 nflh_stripe_count; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
<t> | ||||
The generic layout hint structure is described | The generic layout hint structure is described | |||
in <xref target="layouthint4" />. The client uses the | in <xref target="layouthint4" format="default"/>. The client uses the | |||
layout hint in the layout_hint (<xref | layout hint in the layout_hint (<xref target="attrdef_layout_hint" format=" | |||
target="attrdef_layout_hint" />) attribute to indicate the preferred type | default"/>) attribute to indicate the preferred type | |||
of layout to be used for a newly created file. The | of layout to be used for a newly created file. The | |||
LAYOUT4_NFSV4_1_FILES layout-type-specific content for the | LAYOUT4_NFSV4_1_FILES layout-type-specific content for the | |||
layout hint is composed of three fields. The first field, | layout hint is composed of three fields. The first field, | |||
nflh_care, is a set of flags indicating which values of the hint the | nflh_care, is a set of flags indicating which values of the hint the | |||
client cares about. If the NFLH4_CARE_DENSE flag is set, then | client cares about. If the NFLH4_CARE_DENSE flag is set, then | |||
the client indicates in the second field, nflh_util, | the client indicates in the second field, nflh_util, | |||
a preference for how the data | a preference for how the data | |||
file is packed (<xref target="sparse_dense" />), which is controlled | file is packed (<xref target="sparse_dense" format="default"/>), which is c ontrolled | |||
by the value of the expression nflh_util & NFL4_UFLG_DENSE ("&" rep resents the bitwise AND operator). If the | by the value of the expression nflh_util & NFL4_UFLG_DENSE ("&" rep resents the bitwise AND operator). If the | |||
NFLH4_CARE_COMMIT_THRU_MDS flag is set, then the client indicates | NFLH4_CARE_COMMIT_THRU_MDS flag is set, then the client indicates | |||
a preference for whether the client should send COMMIT operations | a preference for whether the client should send COMMIT operations | |||
to the metadata server or data server (<xref target="commit_thru_mds" />), | to the metadata server or data server (<xref target="commit_thru_mds" forma t="default"/>), | |||
which is controlled by the value of nflh_util & NFL4_UFLG_COMMIT_THRU_M DS. | which is controlled by the value of nflh_util & NFL4_UFLG_COMMIT_THRU_M DS. | |||
If the NFLH4_CARE_STRIPE_UNIT_SIZE flag is set, the client indicates | If the NFLH4_CARE_STRIPE_UNIT_SIZE flag is set, the client indicates | |||
its preferred stripe unit size, which is indicated in | its preferred stripe unit size, which is indicated in | |||
nflh_util & | nflh_util & | |||
NFL4_UFLG_STRIPE_UNIT_SIZE_MASK (thus, the stripe | NFL4_UFLG_STRIPE_UNIT_SIZE_MASK (thus, the stripe | |||
unit size MUST be a multiple of 64 bytes). The minimum stripe unit | unit size <bcp14>MUST</bcp14> be a multiple of 64 bytes). The minimum strip e unit | |||
size is 64 bytes. | size is 64 bytes. | |||
If the NFLH4_CARE_STRIPE_COUNT flag is set, the client indicates | If the NFLH4_CARE_STRIPE_COUNT flag is set, the client indicates | |||
in the third field, | in the third field, | |||
nflh_stripe_count, the stripe count. The stripe count multiplied | nflh_stripe_count, the stripe count. The stripe count multiplied | |||
by the stripe unit size is the stripe width. | by the stripe unit size is the stripe width. | |||
</t> | </t> | |||
<t> | <t> | |||
When LAYOUTGET returns a LAYOUT4_NFSV4_1_FILES layout | When LAYOUTGET returns a LAYOUT4_NFSV4_1_FILES layout | |||
(indicated in the loc_type field of the lo_content field), | (indicated in the loc_type field of the lo_content field), | |||
the loc_body field of the lo_content field | the loc_body field of the lo_content field | |||
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> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | 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<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
<t> | ||||
The nfsv4_1_file_layout_ds_addr4 data type represents the | The nfsv4_1_file_layout_ds_addr4 data type represents the | |||
device address. It is composed of two fields: | device address. It is composed of two fields: | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
nflda_multipath_ds_list: An array of lists of data servers, where | nflda_multipath_ds_list: An array of lists of data servers, where | |||
each list can be one or more elements, and each element represents | each list can be one or more elements, and each element represents | |||
a data server address that may serve equally as the target of I/O operations (see | a data server address that may serve equally as the target of I/O operations (see | |||
<xref target="file_multipath" />). | <xref target="file_multipath" format="default"/>). | |||
The length of this array might be different than the stripe count. | The length of this array might be different than the stripe count. | |||
</t> | </li> | |||
<t> | <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 M UST | 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 SHOULD 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. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
/* | /* | |||
* 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<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | <t> | |||
<t> | ||||
The nfsv4_1_file_layout4 data type represents the layout. | The nfsv4_1_file_layout4 data type represents the layout. | |||
It is composed of the following fields: | It is composed of the following fields: | |||
<list style='numbers'> | </t> | |||
<ol spacing="normal" type="1"> | ||||
<t> | <li> | |||
nfl_deviceid: The device ID that maps to a value of type | nfl_deviceid: The device ID that maps to a value of type | |||
nfsv4_1_file_layout_ds_addr4. | nfsv4_1_file_layout_ds_addr4. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
nfl_util: Like the nflh_util field of data type nfsv4_1_file_layouthint4, | nfl_util: Like the nflh_util field of data type nfsv4_1_file_layouthint4, | |||
a compact representation of how the data on a file | a compact representation of how the data on a file | |||
on each data server is packed, whether the client should send | on each data server is packed, whether the client should send | |||
COMMIT operations to the metadata server or data server, and the | COMMIT operations to the metadata server or data server, and the | |||
stripe unit size. If a server returns two or | stripe unit size. If a server returns two or | |||
more overlapping layouts, each stripe unit size in | more overlapping layouts, each stripe unit size in | |||
each overlapping layout MUST be the same. | each overlapping layout <bcp14>MUST</bcp14> be the same. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
nfl_first_stripe_index: The index into the first element | nfl_first_stripe_index: The index into the first element | |||
of the nflda_stripe_indices array to use. | of the nflda_stripe_indices array to use. | |||
</t> | </li> | |||
<li> | ||||
<t> | <t> | |||
nfl_pattern_offset: | nfl_pattern_offset: | |||
This field is the logical offset into the file | This field is the logical offset into the file | |||
where the striping pattern starts. It is required for | where the striping pattern starts. It is required for | |||
converting the client's logical I/O offset (e.g., the current | converting the client's logical I/O offset (e.g., the current | |||
offset in a POSIX file descriptor before the read() or write() | offset in a POSIX file descriptor before the read() or write() | |||
system call is sent) into the stripe unit number (see | system call is sent) into the stripe unit number (see | |||
<xref target="SUi"/>). | <xref target="SUi" format="default"/>). | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
If dense packing is used, then nfl_pattern_offset | If dense packing is used, then nfl_pattern_offset | |||
is also needed to convert the client's logical | is also needed to convert the client's logical | |||
I/O offset to an offset on the file on the data | I/O offset to an offset on the file on the data | |||
server corresponding to the stripe unit number (see <xref | server corresponding to the stripe unit number (see <xref target="sparse_de | |||
target="sparse_dense"/>). | nse" format="default"/>). | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
Note that nfl_pattern_offset is not always the same as | Note that nfl_pattern_offset is not always the same as | |||
lo_offset. For example, via the LAYOUTGET operation, | lo_offset. For example, via the LAYOUTGET operation, | |||
a client might request a layout starting at offset 1000 of a | a client might request a layout starting at offset 1000 of a | |||
file that has its striping pattern start at offset zero. | file that has its striping pattern start at offset zero. | |||
<vspace blankLines='1' /> | </t> | |||
</li> | ||||
</t> | <li> | |||
<t> | ||||
<t> | ||||
nfl_fh_list: An array of data server filehandles for each | nfl_fh_list: An array of data server filehandles for each | |||
list of data servers in each element of the nflda_multipath_ds_list | list of data servers in each element of the nflda_multipath_ds_list | |||
array. The number of elements in | array. The number of elements in | |||
nfl_fh_list depends on whether sparse or dense packing | nfl_fh_list depends on whether sparse or dense packing | |||
is being used. | is being used. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
If sparse packing is being used, the number of elements in | If sparse packing is being used, the number of elements in | |||
nfl_fh_list MUST be one of three values: | nfl_fh_list <bcp14>MUST</bcp14> be one of three values: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Zero. This means that filehandles used | Zero. This means that filehandles used | |||
for each data server are the same as the | for each data server are the same as the | |||
filehandle returned by the OPEN operation | filehandle returned by the OPEN operation | |||
from the metadata server. | from the metadata server. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
One. This means that every data server uses | One. This means that every data server uses | |||
the same filehandle: what is specified in | the same filehandle: what is specified in | |||
nfl_fh_list[0]. | nfl_fh_list[0]. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
The same number of elements in | The same number of elements in | |||
nflda_multipath_ds_list. Thus, in this case, | nflda_multipath_ds_list. Thus, in this case, | |||
when sending an I/O operation to any data server in | when sending an I/O operation to any data server in | |||
nflda_multipath_ds_list[X], the filehandle | nflda_multipath_ds_list[X], the filehandle | |||
in nfl_fh_list[X] MUST be used. | in nfl_fh_list[X] <bcp14>MUST</bcp14> be used. | |||
</t> | ||||
</list> | ||||
See the discussion on sparse packing in <xref target="sparse_dense" />. | </li> | |||
<vspace blankLines='1' /> | </ul> | |||
</t> | <t> | |||
<t> | See the discussion on sparse packing in <xref target="sparse_dense" format= | |||
"default"/>. | ||||
</t> | ||||
</li> | ||||
<li> | ||||
<t> | ||||
If dense packing is being used, the number of elements | If dense packing is being used, the number of elements | |||
in nfl_fh_list MUST be the same as the number | in nfl_fh_list <bcp14>MUST</bcp14> be the same as the number | |||
of elements in nflda_stripe_indices. Thus, | of elements in nflda_stripe_indices. Thus, | |||
when sending an I/O operation to any data server in | when sending an I/O operation to any data server in | |||
nflda_multipath_ds_list[nflda_stripe_indices[Y]], | nflda_multipath_ds_list[nflda_stripe_indices[Y]], | |||
the filehandle in nfl_fh_list[Y] MUST be | the filehandle in nfl_fh_list[Y] <bcp14>MUST</bcp14> be | |||
used. In addition, any time there exists i | used. In addition, any time there exists i | |||
and j, (i != j), such that the intersection of | and j, (i != j), such that the intersection of | |||
nflda_multipath_ds_list[nflda_stripe_indices[i]] | nflda_multipath_ds_list[nflda_stripe_indices[i]] | |||
and nflda_multipath_ds_list[nflda_stripe_indices[j]] | and nflda_multipath_ds_list[nflda_stripe_indices[j]] | |||
is not empty, then nfl_fh_list[i] MUST NOT equal | is not empty, then nfl_fh_list[i] <bcp14>MUST NOT</bcp14> equal | |||
nfl_fh_list[j]. In other words, when dense packing | nfl_fh_list[j]. In other words, when dense packing | |||
is being used, if a data server appears in two or more | is being used, if a data server appears in two or more | |||
units of a striping pattern, each reference to | units of a striping pattern, each reference to | |||
the data server MUST use a different filehandle. | the data server <bcp14>MUST</bcp14> use a different filehandle. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
Indeed, if there are multiple striping patterns, | Indeed, if there are multiple striping patterns, | |||
as indicated by the presence of multiple objects of | as indicated by the presence of multiple objects of | |||
data type layout4 (either returned in one or multiple | data type layout4 (either returned in one or multiple | |||
LAYOUTGET operations), and a data server is the target | LAYOUTGET operations), and a data server is the target | |||
of a unit of one pattern and another unit of another | of a unit of one pattern and another unit of another | |||
pattern, then each reference to each data server MUST | pattern, then each reference to each data server <bcp14>MUST</bcp14> | |||
use a different filehandle. | use a different filehandle. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
See the discussion on dense packing in <xref target="sparse_dense" />. | See the discussion on dense packing in <xref target="sparse_dense" format=" default"/>. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ul> | |||
</list> | </li> | |||
</ol> | ||||
<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" />. | <xref target="file_layout_interpret" format="default"/>. | |||
</t> | ||||
</section> <!-- "File Layout Data Types" "file_data_types" --> | ||||
<section title="Interpreting the File Layout" | ||||
anchor="file_layout_interpret"> | ||||
<section title="Determining the Stripe Unit Number" anchor="SUi"> | ||||
<t> | </t> | |||
</section> | ||||
<section anchor="file_layout_interpret" numbered="true" toc="default"> | ||||
<name>Interpreting the File Layout</name> | ||||
<section anchor="SUi" numbered="true" toc="default"> | ||||
<name>Determining the Stripe Unit Number</name> | ||||
<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: | |||
<figure> | </t> | |||
<artwork><![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); | SUi = floor(relative_offset / stripe_unit_size);]]></sourcecode> | |||
]]></artwork> | </section> | |||
</figure> | <section numbered="true" toc="default"> | |||
<name>Interpreting the File Layout Using Sparse Packing</name> | ||||
</t> | <t> | |||
</section> | ||||
<section title="Interpreting the File Layout Using Sparse Packing"> | ||||
<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> | |||
<figure> | <sourcecode type="pseudocode"><![CDATA[ | |||
<artwork><![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 21880 ¶ | skipping to change at line 21936 ¶ | |||
case 0: | case 0: | |||
fh = filehandle returned by OPEN; | fh = filehandle returned by OPEN; | |||
break; | break; | |||
default: | default: | |||
throw a fatal exception; | throw a fatal exception; | |||
break; | break; | |||
} | } | |||
address_list = nflda_multipath_ds_list[idx]; | address_list = nflda_multipath_ds_list[idx];]]></sourcecode> | |||
<t> | ||||
]]></artwork> | ||||
</figure> | ||||
<t> | ||||
The client would then select a data server from address_list, and | The client would then select a data server from address_list, and | |||
send a READ or WRITE operation using the filehandle specified in fh. | send a READ or WRITE operation using the filehandle specified in fh. | |||
</t> | </t> | |||
<t> | <t> | |||
Consider the following example: | Consider the following example: | |||
</t> | </t> | |||
<t> | <t> | |||
Suppose we have a device address consisting of seven | Suppose we have a device address consisting of seven | |||
data servers, arranged in three equivalence (<xref | data servers, arranged in three equivalence (<xref target="file_multipath" for | |||
target="file_multipath" />) classes: | mat="default"/>) classes: | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
{ A, B, C, D }, { E }, { F, G } | { A, B, C, D }, { E }, { F, G } | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
where A through G are network addresses. | where A through G are network addresses. | |||
</t> | </t> | |||
<t> | <t> | |||
Then | Then | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nflda_multipath_ds_list<> = { A, B, C, D }, { E }, { F, G } | nflda_multipath_ds_list<> = { A, B, C, D }, { E }, { F, G } | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
i.e., | i.e., | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nflda_multipath_ds_list[0] = { A, B, C, D } | nflda_multipath_ds_list[0] = { A, B, C, D } | |||
</t> | </li> | |||
<t> | <li> | |||
nflda_multipath_ds_list[1] = { E } | nflda_multipath_ds_list[1] = { E } | |||
</t> | </li> | |||
<t> | <li> | |||
nflda_multipath_ds_list[2] = { F, G } | nflda_multipath_ds_list[2] = { F, G } | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Suppose the striping index array is: | Suppose the striping index array is: | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nflda_stripe_indices<> = { 2, 0, 1, 0 } | nflda_stripe_indices<> = { 2, 0, 1, 0 } | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Now suppose the client gets a layout that has a device ID | Now suppose the client gets a layout that has a device ID | |||
that maps to the above device address. The initial index contains | that maps to the above device address. The initial index contains | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nfl_first_stripe_index = 2, | nfl_first_stripe_index = 2, | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
and the filehandle list is | and the filehandle list is | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nfl_fh_list = { 0x36, 0x87, 0x67 }. | nfl_fh_list = { 0x36, 0x87, 0x67 }. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
If the client wants to write to SU0, the | If the client wants to write to SU0, the | |||
set of valid { network address, filehandle } combinations | set of valid { network address, filehandle } combinations | |||
for SUi are determined by: | for SUi are determined by: | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nfl_first_stripe_index = 2 | nfl_first_stripe_index = 2 | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
So | So | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
<t> | ||||
idx = nflda_stripe_indices[(0 + 2) % 4] | idx = nflda_stripe_indices[(0 + 2) % 4] | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
= nflda_stripe_indices[2] | = nflda_stripe_indices[2] | |||
</t> | </li> | |||
<t> | <li> | |||
= 1 | = 1 | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
So | So | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nflda_multipath_ds_list[1] = { E } | nflda_multipath_ds_list[1] = { E } | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
and | and | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nfl_fh_list[1] = { 0x87 } | nfl_fh_list[1] = { 0x87 } | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The client can thus write SU0 to { 0x87, { E } }. | The client can thus write SU0 to { 0x87, { E } }. | |||
</t> | </t> | |||
<t> | <t> | |||
The destinations of the first 13 storage units are: | The destinations of the first 13 storage units are: | |||
</t> | </t> | |||
<texttable> | <!-- [rfced] We're curious why tables 9 and 10 contain blank lines? They don't | |||
appear in the original. We're trying to understand the best XML to use to | ||||
<ttcol>SUi</ttcol> <ttcol>filehandle</ttcol> <ttcol>data servers</ttcol> | format this table, and we wonder whether the breaks are necssary. | |||
--> | ||||
<c>0</c> <c> 87 </c><c> E </c> | <table align="center"> | |||
<c>1</c><c>36</c><c>A,B,C,D</c> | <thead> | |||
<c>2</c><c>67</c><c>F,G</c> | <tr> | |||
<c>3</c><c>36 </c><c>A,B,C,D</c> | <th align="left">SUi</th> | |||
<th align="left">filehandle</th> | ||||
<c/> <c/> <c/> | <th align="left">data servers</th> | |||
</tr> | ||||
<c>4</c><c>87</c><c>E</c> | </thead> | |||
<c>5</c><c>36</c><c>A,B,C,D</c> | <tbody> | |||
<c>6</c><c>67</c><c>F,G</c> | <tr> | |||
<c>7</c><c>36</c><c>A,B,C,D</c> | <td align="left">0</td> | |||
<td align="left">87 </td> | ||||
<c/> <c/> <c/> | <td align="left">E </td> | |||
<c>8</c><c>87</c><c>E</c> | </tr> | |||
<c>9</c><c>36</c><c>A,B,C,D</c> | <tr> | |||
<c>10</c><c>67</c><c>F,G</c> | <td align="left">1</td> | |||
<c>11</c><c>36</c><c>A,B,C,D</c> | <td align="left">36</td> | |||
<td align="left">A,B,C,D</td> | ||||
<c/> <c/> <c/> | </tr> | |||
<tr> | ||||
<c>12</c><c>87</c><c>E</c> | <td align="left">2</td> | |||
<td align="left">67</td> | ||||
</texttable> | <td align="left">F,G</td> | |||
</section> | </tr> | |||
<section title="Interpreting the File Layout Using Dense Packing"> | <tr> | |||
<t> | <td align="left">3</td> | |||
<td align="left">36 </td> | ||||
<td align="left">A,B,C,D</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"/> | ||||
<td align="left"/> | ||||
<td align="left"/> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">4</td> | ||||
<td align="left">87</td> | ||||
<td align="left">E</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">5</td> | ||||
<td align="left">36</td> | ||||
<td align="left">A,B,C,D</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">6</td> | ||||
<td align="left">67</td> | ||||
<td align="left">F,G</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">7</td> | ||||
<td align="left">36</td> | ||||
<td align="left">A,B,C,D</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"/> | ||||
<td align="left"/> | ||||
<td align="left"/> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">8</td> | ||||
<td align="left">87</td> | ||||
<td align="left">E</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">9</td> | ||||
<td align="left">36</td> | ||||
<td align="left">A,B,C,D</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">10</td> | ||||
<td align="left">67</td> | ||||
<td align="left">F,G</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">11</td> | ||||
<td align="left">36</td> | ||||
<td align="left">A,B,C,D</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"/> | ||||
<td align="left"/> | ||||
<td align="left"/> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">12</td> | ||||
<td align="left">87</td> | ||||
<td align="left">E</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
</section> | ||||
<section numbered="true" toc="default"> | ||||
<name>Interpreting the File Layout Using Dense Packing</name> | ||||
<t> | ||||
When dense packing is used, the algorithm for determining the filehandle and s et | When dense packing is used, the algorithm for determining the filehandle and s et | |||
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> | |||
<figure> | <sourcecode type="pseudocode"><![CDATA[ | |||
<artwork><![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) { | |||
case stripe_count: | case stripe_count: | |||
fh = nfl_fh_list[j]; | fh = nfl_fh_list[j]; | |||
break; | break; | |||
default: | default: | |||
throw a fatal exception; | throw a fatal exception; | |||
break; | break; | |||
} | } | |||
address_list = nflda_multipath_ds_list[idx]; | address_list = nflda_multipath_ds_list[idx];]]></sourcecode> | |||
<t> | ||||
]]></artwork> | ||||
</figure> | ||||
<t> | ||||
The client would then select a data server from address_list, and | The client would then select a data server from address_list, and | |||
send a READ or WRITE operation using the filehandle specified in fh. | send a READ or WRITE operation using the filehandle specified in fh. | |||
</t> | </t> | |||
<t> | <t> | |||
Consider the following example (which is the same | Consider the following example (which is the same | |||
as the sparse packing example, except for the | as the sparse packing example, except for the | |||
filehandle list): | filehandle list): | |||
</t> | </t> | |||
<t> | <t> | |||
Suppose we have a device address consisting of seven | Suppose we have a device address consisting of seven | |||
data servers, arranged in three equivalence (<xref | data servers, arranged in three equivalence (<xref target="file_multipath" for | |||
target="file_multipath" />) classes: | mat="default"/>) classes: | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
{ A, B, C, D }, { E }, { F, G } | { A, B, C, D }, { E }, { F, G } | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
where A through G are network addresses. | where A through G are network addresses. | |||
</t> | </t> | |||
<t> | <t> | |||
Then | Then | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nflda_multipath_ds_list<> = { A, B, C, D }, { E }, { F, G } | nflda_multipath_ds_list<> = { A, B, C, D }, { E }, { F, G } | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
i.e., | i.e., | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nflda_multipath_ds_list[0] = { A, B, C, D } | nflda_multipath_ds_list[0] = { A, B, C, D } | |||
</t> | </li> | |||
<t> | <li> | |||
nflda_multipath_ds_list[1] = { E } | nflda_multipath_ds_list[1] = { E } | |||
</t> | </li> | |||
<t> | <li> | |||
nflda_multipath_ds_list[2] = { F, G } | nflda_multipath_ds_list[2] = { F, G } | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Suppose the striping index array is: | Suppose the striping index array is: | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nflda_stripe_indices<> = { 2, 0, 1, 0 } | nflda_stripe_indices<> = { 2, 0, 1, 0 } | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Now suppose the client gets a layout that has a device ID | Now suppose the client gets a layout that has a device ID | |||
that maps to the above device address. The initial index contains | that maps to the above device address. The initial index contains | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nfl_first_stripe_index = 2, | nfl_first_stripe_index = 2, | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
and | and | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nfl_fh_list = { 0x67, 0x37, 0x87, 0x36 }. | nfl_fh_list = { 0x67, 0x37, 0x87, 0x36 }. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The interesting examples for dense packing are | The interesting examples for dense packing are | |||
SU1 and SU3 because each stripe unit refers to the | SU1 and SU3 because each stripe unit refers to the | |||
same data server list, yet each stripe unit MUST use a different filehandle. | same data server list, yet each stripe unit <bcp14>MUST</bcp14> use a differen t filehandle. | |||
If the client wants to write to SU1, the | If the client wants to write to SU1, the | |||
set of valid { network address, filehandle } combinations | set of valid { network address, filehandle } combinations | |||
for SUi are determined by: | for SUi are determined by: | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
nfl_first_stripe_index = 2 | <li> nfl_first_stripe_index = 2 </li> | |||
</t> | </ul> | |||
</list> | <t> | |||
</t> | ||||
<t> | ||||
So | So | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
j = (1 + 2) % 4 = 3 | <li> | |||
<list style='empty'> | <t> j = (1 + 2) % 4 = 3 </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
idx = nflda_stripe_indices[j] | <li> idx = nflda_stripe_indices[j] </li> | |||
</t> | <li> = nflda_stripe_indices[3] </li> | |||
<t> | <li> = 0 </li> | |||
= nflda_stripe_indices[3] | </ul> | |||
</t> | </li> | |||
<t> | </ul> | |||
= 0 | <t> | |||
</t> | ||||
</list> | ||||
</t> | ||||
</list> | ||||
</t> | ||||
<t> | ||||
So | So | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nflda_multipath_ds_list[0] = { A, B, C, D } | nflda_multipath_ds_list[0] = { A, B, C, D } | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
and | and | |||
<list style='empty'> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
nfl_fh_list[3] = { 0x36 } | nfl_fh_list[3] = { 0x36 } | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The client can thus write SU1 to { 0x36, { A, B, C, D } }. | The client can thus write SU1 to { 0x36, { A, B, C, D } }. | |||
</t> | </t> | |||
<t> | <t> | |||
For SU3, j = (3 + 2) % 4 = 1, and nflda_stripe_indices[1] = 0. | For SU3, j = (3 + 2) % 4 = 1, and nflda_stripe_indices[1] = 0. | |||
Then nflda_multipath_ds_list[0] = { A, B, C, D }, and | Then nflda_multipath_ds_list[0] = { A, B, C, D }, and | |||
nfl_fh_list[1] = 0x37. The client can thus write SU3 to | nfl_fh_list[1] = 0x37. The client can thus write SU3 to | |||
{ 0x37, { A, B, C, D } }. | { 0x37, { A, B, C, D } }. | |||
</t> | </t> | |||
<t> | <t> | |||
The destinations of the first 13 storage units are: | The destinations of the first 13 storage units are: | |||
</t> | </t> | |||
<texttable> | <table align="center"> | |||
<thead> | ||||
<ttcol>SUi</ttcol> <ttcol>filehandle</ttcol> <ttcol>data servers</ttcol> | <tr> | |||
<th align="left">SUi</th> | ||||
<c>0</c> <c> 87 </c><c> E </c> | <th align="left">filehandle</th> | |||
<c>1</c><c>36</c><c>A,B,C,D</c> | <th align="left">data servers</th> | |||
<c>2</c><c>67</c><c>F,G</c> | </tr> | |||
<c>3</c><c>37 </c><c>A,B,C,D</c> | </thead> | |||
<tbody> | ||||
<c/> <c/> <c/> | <tr> | |||
<td align="left">0</td> | ||||
<c>4</c><c>87</c><c>E</c> | <td align="left"> 87 </td> | |||
<c>5</c><c>36</c><c>A,B,C,D</c> | <td align="left"> E </td> | |||
<c>6</c><c>67</c><c>F,G</c> | </tr> | |||
<c>7</c><c>37</c><c>A,B,C,D</c> | <tr> | |||
<td align="left">1</td> | ||||
<c/> <c/> <c/> | <td align="left">36</td> | |||
<c>8</c><c>87</c><c>E</c> | <td align="left">A,B,C,D</td> | |||
<c>9</c><c>36</c><c>A,B,C,D</c> | </tr> | |||
<c>10</c><c>67</c><c>F,G</c> | <tr> | |||
<c>11</c><c>37</c><c>A,B,C,D</c> | <td align="left">2</td> | |||
<td align="left">67</td> | ||||
<c/> <c/> <c/> | <td align="left">F,G</td> | |||
</tr> | ||||
<c>12</c><c>87</c><c>E</c> | <tr> | |||
<td align="left">3</td> | ||||
</texttable> | <td align="left">37 </td> | |||
</section> | <td align="left">A,B,C,D</td> | |||
</tr> | ||||
<section title="Sparse and Dense Stripe Unit Packing" | <tr> | |||
anchor="sparse_dense"> | <td align="left"/> | |||
<t> | <td align="left"/> | |||
<td align="left"/> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">4</td> | ||||
<td align="left">87</td> | ||||
<td align="left">E</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">5</td> | ||||
<td align="left">36</td> | ||||
<td align="left">A,B,C,D</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">6</td> | ||||
<td align="left">67</td> | ||||
<td align="left">F,G</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">7</td> | ||||
<td align="left">37</td> | ||||
<td align="left">A,B,C,D</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"/> | ||||
<td align="left"/> | ||||
<td align="left"/> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">8</td> | ||||
<td align="left">87</td> | ||||
<td align="left">E</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">9</td> | ||||
<td align="left">36</td> | ||||
<td align="left">A,B,C,D</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">10</td> | ||||
<td align="left">67</td> | ||||
<td align="left">F,G</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">11</td> | ||||
<td align="left">37</td> | ||||
<td align="left">A,B,C,D</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"/> | ||||
<td align="left"/> | ||||
<td align="left"/> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">12</td> | ||||
<td align="left">87</td> | ||||
<td align="left">E</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
</section> | ||||
<section anchor="sparse_dense" numbered="true" toc="default"> | ||||
<name>Sparse and Dense Stripe Unit Packing</name> | ||||
<t> | ||||
The flag NFL4_UFLG_DENSE of the nfl_util4 data type (field nflh_util of the | The flag NFL4_UFLG_DENSE of the nfl_util4 data type (field nflh_util of the | |||
data type nfsv4_1_file_layouthint4 and field nfl_util of | data type nfsv4_1_file_layouthint4 and field nfl_util of | |||
data type nfsv4_1_file_layout_ds_addr4) specifies how the data | data type nfsv4_1_file_layout_ds_addr4) specifies how the data | |||
is packed within the | is packed within the | |||
data file on a data server. It allows for two different data | data file on a data server. It allows for two different data | |||
packings: sparse and dense. The packing type determines the | packings: sparse and dense. The packing type determines the | |||
calculation that will be made to map the client-visible file offset | calculation that will be made to map the client-visible file offset | |||
to the offset within the data file located on the data server. | to the offset within the data file located on the data server. | |||
</t> | </t> | |||
<t> | <t> | |||
If nfl_util & NFL4_UFLG_DENSE is zero, this means that | If nfl_util & NFL4_UFLG_DENSE is zero, this means that | |||
sparse packing is being used. Hence, the logical offsets of the | sparse packing is being used. Hence, the logical offsets of the | |||
file as viewed by a client | file as viewed by a client | |||
sending READs and WRITEs directly to the metadata server | sending READs and WRITEs directly to the metadata server | |||
are the same offsets each data server uses when storing | are the same offsets each data server uses when storing | |||
a stripe unit. The effect then, for striping patterns | a stripe unit. The effect then, for striping patterns | |||
consisting of at least two stripe units, is for each | consisting of at least two stripe units, is for each | |||
data server file to be sparse or "holey". So for example, | data server file to be sparse or "holey". So for example, | |||
suppose there is a pattern with three stripe units, the stripe unit | suppose there is a pattern with three stripe units, the stripe unit | |||
size is 4096 bytes, and there are three data servers in | size is 4096 bytes, and there are three data servers in | |||
the pattern. Then, the file in data server 1 will have | the pattern. Then, the file in data server 1 will have | |||
stripe units 0, 3, 6, 9, ... filled; data server 2's | stripe units 0, 3, 6, 9, ... filled; data server 2's | |||
file will have stripe units 1, 4, 7, 10, ... filled; | file will have stripe units 1, 4, 7, 10, ... filled; | |||
and data server 3's file will have stripe units 2, | and data server 3's file will have stripe units 2, | |||
5, 8, 11, ... filled. The unfilled stripe units of | 5, 8, 11, ... filled. The unfilled stripe units of | |||
each file will be holes; hence, the files in each data | each file will be holes; hence, the files in each data | |||
server are sparse. | server are sparse. | |||
</t> | </t> | |||
<t> | <t> | |||
If sparse packing is being used and a client attempts I/O to one of | If sparse packing is being used and a client attempts I/O to one of | |||
the holes, then an error MUST be | the holes, then an error <bcp14>MUST</bcp14> be | |||
returned by the data server. Using the above example, if data server 3 receiv ed a READ or WRITE operation for block 4, the data server | returned by the data server. Using the above example, if data server 3 receiv ed a READ or WRITE operation for block 4, the data server | |||
would return NFS4ERR_PNFS_IO_HOLE. Thus, | would return NFS4ERR_PNFS_IO_HOLE. Thus, | |||
data servers need to understand the striping pattern in order | data servers need to understand the striping pattern in order | |||
to support sparse packing. | to support sparse packing. | |||
</t> | </t> | |||
<t> | <t> | |||
If nfl_util & NFL4_UFLG_DENSE is one, this means that | If nfl_util & NFL4_UFLG_DENSE is one, this means that | |||
dense packing is being used, and the data server files have no holes. | dense packing is being used, and the data server files have no holes. | |||
Dense packing might be selected because the data server does not | Dense packing might be selected because the data server does not | |||
(efficiently) support holey files or because the data server | (efficiently) support holey files or because the data server | |||
cannot recognize read-ahead unless there are no holes. | cannot recognize read-ahead unless there are no holes. | |||
If dense packing is indicated in the layout, | If dense packing is indicated in the layout, | |||
the data files will be packed. Using the | the data files will be packed. Using the | |||
same striping pattern and stripe unit size that were used for | same striping pattern and stripe unit size that were used for | |||
the sparse packing example, the corresponding dense packing example would hav e | the sparse packing example, the corresponding dense packing example would hav e | |||
all stripe units of all data files filled as follows: | all stripe units of all data files filled as follows: | |||
<list style='symbols'> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <li> | |||
Logical stripe units 0, 3, 6, ... of the file would live on | Logical stripe units 0, 3, 6, ... of the file would live on | |||
stripe units 0, 1, 2, ... of the file of data server 1. | stripe units 0, 1, 2, ... of the file of data server 1. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
Logical stripe units 1, 4, 7, ... of the file would live on | Logical stripe units 1, 4, 7, ... of the file would live on | |||
stripe units 0, 1, 2, ... of the file of data server 2. | stripe units 0, 1, 2, ... of the file of data server 2. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
Logical stripe units 2, 5, 8, ... of the file would live on | Logical stripe units 2, 5, 8, ... of the file would live on | |||
stripe units 0, 1, 2, ... of the file of data server 3. | stripe units 0, 1, 2, ... of the file of data server 3. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <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> | |||
<figure> | <sourcecode type="pseudocode"><![CDATA[ | |||
<artwork><![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 | + relative_offset % stripe_unit_size]]></sourcecode> | |||
]]></artwork> | <t> | |||
</figure> | ||||
<t> | ||||
If dense packing is being used, and a data server appears | If dense packing is being used, and a data server appears | |||
more than once in a striping pattern, then to distinguish | more than once in a striping pattern, then to distinguish | |||
one stripe unit from another, the data server MUST use a | one stripe unit from another, the data server <bcp14>MUST</bcp14> use a | |||
different filehandle. Let's suppose there are two data | different filehandle. Let's suppose there are two data | |||
servers. Logical stripe units 0, 3, 6 are served by | servers. Logical stripe units 0, 3, 6 are served by | |||
data server 1; logical stripe units 1, 4, 7 are served | data server 1; logical stripe units 1, 4, 7 are served | |||
by data server 2; and logical stripe units 2, 5, 8 are | by data server 2; and logical stripe units 2, 5, 8 are | |||
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> <!-- "Interpreting the File Layout" anchor="file_layout_interpret" - | ||||
-> | ||||
<section title="Data Server Multipathing" anchor="file_multipath"> | <section anchor="file_multipath" numbered="true" toc="default"> | |||
<t> | <name>Data Server Multipathing</name> | |||
<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" | bandwidth scaling via trunking (<xref target="Trunking" format="default"/>) an | |||
/>) and for higher availability of use in the case of | d 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 | |||
of another data server that is exporting the | of another data server that is exporting the | |||
same data stripe unit, without having to contact the | same data stripe unit, without having to contact the | |||
metadata server for a new layout. | metadata server for a new layout. | |||
</t> | </t> | |||
<t> | <t> | |||
To support data server multipathing, each element of | To support data server multipathing, each element of | |||
the nflda_multipath_ds_list contains an array of one | the nflda_multipath_ds_list contains an array of one | |||
more data server network addresses. This array (data | more data server network addresses. This array (data | |||
type multipath_list4) represents a list of data servers | type multipath_list4) represents a list of data servers | |||
(each identified by a network address), with the possibility | (each identified by a network address), with the possibility | |||
that some data servers will appear in the list multiple times. | that some data servers will appear in the list multiple times. | |||
</t> | </t> | |||
<t> | <t> | |||
The client is free to use any of the network addresses | The client is free to use any of the network addresses | |||
as a destination to send data server requests. If some | as a destination to send data server requests. If some | |||
network addresses are less optimal paths to the data than | network addresses are less optimal paths to the data than | |||
others, then the MDS SHOULD NOT include those network | others, then the MDS <bcp14>SHOULD NOT</bcp14> include those network | |||
addresses in an element of nflda_multipath_ds_list. If | addresses in an element of nflda_multipath_ds_list. If | |||
less optimal network addresses exist to provide failover, the | less optimal network addresses exist to provide failover, the | |||
RECOMMENDED method to offer the addresses is | <bcp14>RECOMMENDED</bcp14> method to offer the addresses is | |||
to provide them in a replacement device-ID-to-device-address | to provide them in a replacement device-ID-to-device-address | |||
mapping, or a replacement device ID. When | mapping, or a replacement device ID. When | |||
a client finds that no data server in an element of | a client finds that no data server in an element of | |||
nflda_multipath_ds_list responds, it SHOULD send a | nflda_multipath_ds_list responds, it <bcp14>SHOULD</bcp14> send a | |||
GETDEVICEINFO to attempt to replace the existing | GETDEVICEINFO to attempt to replace the existing | |||
device-ID-to-device-address mappings. If the MDS detects | device-ID-to-device-address mappings. If the MDS detects | |||
that all data servers represented by an element of | that all data servers represented by an element of | |||
nflda_multipath_ds_list are unavailable, the MDS SHOULD | nflda_multipath_ds_list are unavailable, the MDS <bcp14>SHOULD</bcp14> | |||
send a CB_NOTIFY_DEVICEID (if the client has indicated | send a CB_NOTIFY_DEVICEID (if the client has indicated | |||
it wants device ID notifications for changed device IDs) | it wants device ID notifications for changed device IDs) | |||
to change the device-ID-to-device-address mappings to | to change the device-ID-to-device-address mappings to | |||
the available data servers. If the device ID itself will | the available data servers. If the device ID itself will | |||
be replaced, the MDS SHOULD recall all layouts with the | be replaced, the MDS <bcp14>SHOULD</bcp14> recall all layouts with the | |||
device ID, and thus force the client to get new layouts | device ID, and thus force the client to get new layouts | |||
and device ID mappings via LAYOUTGET and GETDEVICEINFO. | and device ID mappings via LAYOUTGET and GETDEVICEINFO. | |||
</t> | </t> | |||
<t> | <t> | |||
Generally, if two network addresses appear in an element | Generally, if two network addresses appear in an element | |||
of nflda_multipath_ds_list, they will designate the same | of nflda_multipath_ds_list, they will designate the same | |||
data server, and the two data server addresses will | data server, and the two data server addresses will | |||
support the implementation of | support the implementation of | |||
client ID or session trunking (the latter is RECOMMENDED) | client ID or session trunking (the latter is <bcp14>RECOMMENDED</bcp14>) | |||
as defined in <xref target="Trunking"/>. The two | as defined in <xref target="Trunking" format="default"/>. The two | |||
data server addresses will share the same server owner | data server addresses will share the same server owner | |||
or major ID of the server owner. It is not always necessary for the | or major ID of the server owner. It is not always necessary for the | |||
two data server addresses to designate the same server | two data server addresses to designate the same server | |||
with trunking being used. For example, | with trunking being used. For example, | |||
the data could be read-only, and the data consist of | the data could be read-only, and the data consist of | |||
exact replicas. | exact replicas. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="ds_ops" numbered="true" toc="default"> | ||||
<section title="Operations Sent to NFSv4.1 Data Servers" anchor="ds_ops"> | <name>Operations Sent to NFSv4.1 Data Servers</name> | |||
<t> | <t> | |||
Clients accessing data on an NFSv4.1 data server MUST send | Clients accessing data on an NFSv4.1 data server <bcp14>MUST</bcp14> send | |||
only the NULL procedure and COMPOUND procedures whose | only the NULL procedure and COMPOUND procedures whose | |||
operations are taken only from two restricted | operations are taken only from two restricted | |||
subsets of the operations defined as valid NFSv4.1 | subsets of the operations defined as valid NFSv4.1 | |||
operations. Clients MUST use the filehandle specified | operations. Clients <bcp14>MUST</bcp14> use the filehandle specified | |||
by the layout when accessing data on NFSv4.1 data | by the layout when accessing data on NFSv4.1 data | |||
servers. | servers. | |||
</t> | </t> | |||
<t> | <t> | |||
The first of these operation subsets consists of management operations. | The first of these operation subsets consists of management operations. | |||
This subset consists of the BACKCHANNEL_CTL, BIND_CONN_TO_SESSION, CREATE_SESS ION, | This subset consists of the BACKCHANNEL_CTL, BIND_CONN_TO_SESSION, CREATE_SESS ION, | |||
DESTROY_CLIENTID, DESTROY_SESSION, EXCHANGE_ID, | DESTROY_CLIENTID, DESTROY_SESSION, EXCHANGE_ID, | |||
SECINFO_NO_NAME, SET_SSV, and SEQUENCE operations. | SECINFO_NO_NAME, SET_SSV, and SEQUENCE operations. | |||
The client may use these operations in order to set | The client may use these operations in order to set | |||
up and maintain the appropriate client IDs, | up and maintain the appropriate client IDs, | |||
sessions, and security contexts involved in communication with the data | sessions, and security contexts involved in communication with the data | |||
server. Henceforth, these will be referred to as | server. Henceforth, these will be referred to as | |||
data-server housekeeping operations. | data-server housekeeping operations. | |||
</t> | </t> | |||
<t> | <t> | |||
The second subset consists of COMMIT, READ, WRITE, and PUTFH. | The second subset consists of COMMIT, READ, WRITE, and PUTFH. | |||
These operations MUST be used with a current filehandle specified by the | These operations <bcp14>MUST</bcp14> be used with a current filehandle specifi | |||
layout. In the case of PUTFH, the new current filehandle MUST be | ed by the | |||
layout. In the case of PUTFH, the new current filehandle <bcp14>MUST</bcp14> | ||||
be | ||||
one taken from the layout. Henceforth, these will be referred to as data-serve r | one taken from the layout. Henceforth, these will be referred to as data-serve r | |||
I/O operations. As described in <xref target="layout_semantics" />, | I/O operations. As described in <xref target="layout_semantics" format="defau | |||
a client MUST NOT send an I/O to a data server for which it does not hold a | lt"/>, | |||
valid layout; the data server MUST reject such an I/O. | a client <bcp14>MUST NOT</bcp14> send an I/O to a data server for which it doe | |||
</t> | s not hold a | |||
<t> | valid layout; the data server <bcp14>MUST</bcp14> reject such an I/O. | |||
</t> | ||||
<t> | ||||
Unless the server has a concurrent non-data-server | Unless the server has a concurrent non-data-server | |||
personality -- i.e., EXCHANGE_ID results returned | personality -- i.e., EXCHANGE_ID results returned | |||
(EXCHGID4_FLAG_USE_PNFS_DS | EXCHGID4_FLAG_USE_PNFS_MDS) | (EXCHGID4_FLAG_USE_PNFS_DS | EXCHGID4_FLAG_USE_PNFS_MDS) | |||
or (EXCHGID4_FLAG_USE_PNFS_DS | EXCHGID4_FLAG_USE_NON_PNFS) see | or (EXCHGID4_FLAG_USE_PNFS_DS | EXCHGID4_FLAG_USE_NON_PNFS) see | |||
<xref target="pnfs_session_stuff"/> -- any attempted use of | <xref target="pnfs_session_stuff" format="default"/> -- any attempted use of | |||
operations against a data server other than those specified in the two | operations against a data server other than those specified in the two | |||
subsets above MUST return | subsets above <bcp14>MUST</bcp14> return | |||
NFS4ERR_NOTSUPP to the client. | NFS4ERR_NOTSUPP to the client. | |||
</t> | </t> | |||
<t> | <t> | |||
When the server has concurrent data-server and | When the server has concurrent data-server and | |||
non-data-server personalities, each COMPOUND sent by the | non-data-server personalities, each COMPOUND sent by the | |||
client MUST be constructed | client <bcp14>MUST</bcp14> be constructed | |||
so that it is appropriate to one of the two personalities, and it | so that it is appropriate to one of the two personalities, and it | |||
MUST NOT contain operations directed to a mix of those | <bcp14>MUST NOT</bcp14> contain operations directed to a mix of those | |||
personalities. The server MUST enforce this. To understand | personalities. The server <bcp14>MUST</bcp14> enforce this. To understand | |||
the constraints, operations within a COMPOUND are divided into | the constraints, operations within a COMPOUND are divided into | |||
the following three classes: | the following three classes: | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
An operation that is ambiguous regarding its personality | An operation that is ambiguous regarding its personality | |||
assignment. This includes all of the data-server | assignment. This includes all of the data-server | |||
housekeeping operations. Additionally, if the | housekeeping operations. Additionally, if the | |||
server has assigned filehandles so that the ones defined | server has assigned filehandles so that the ones defined | |||
by the layout are the same as those used by the metadata | by the layout are the same as those used by the metadata | |||
server, all operations using such filehandles are within this | server, all operations using such filehandles are within this | |||
class, with the following exception. The exception is | class, with the following exception. The exception is | |||
that if the operation uses a stateid that is incompatible with a | that if the operation uses a stateid that is incompatible with a | |||
data-server personality (e.g., a special stateid or the | data-server personality (e.g., a special stateid or the | |||
stateid has a non-zero "seqid" field, see | stateid has a non-zero "seqid" field, see | |||
<xref target="global_stateid"/>), the operation is in class 3, | <xref target="global_stateid" format="default"/>), the operation is in cla ss 3, | |||
as described below. A COMPOUND containing | as described below. A COMPOUND containing | |||
multiple class 1 operations (and operations of no other | multiple class 1 operations (and operations of no other | |||
class) MAY be sent to a server with multiple concurrent data server | class) <bcp14>MAY</bcp14> be sent to a server with multiple concurrent dat a server | |||
and non-data-server personalities. | and non-data-server personalities. | |||
</t> | </li> | |||
<t> | <li> | |||
An operation that is unambiguously referable to the data-server | An operation that is unambiguously referable to the data-server | |||
personality. This includes data-server I/O operations where the | personality. This includes data-server I/O operations where the | |||
filehandle is one that can only be validly directed to the | filehandle is one that can only be validly directed to the | |||
data-server personality. | data-server personality. | |||
</t> | </li> | |||
<t> | <li> | |||
An operation that is unambiguously referable to the non-data-server | An operation that is unambiguously referable to the non-data-server | |||
personality. This includes all COMPOUND operations that are | personality. This includes all COMPOUND operations that are | |||
neither data-server housekeeping nor data-server I/O | neither data-server housekeeping nor data-server I/O | |||
operations, plus data-server I/O operations where the | operations, plus data-server I/O operations where the | |||
current fh (or the one to be made the current fh in the | current fh (or the one to be made the current fh in the | |||
case of PUTFH) is only valid on the metadata | case of PUTFH) is only valid on the metadata | |||
server or where a stateid is used that is incompatible | server or where a stateid is used that is incompatible | |||
with the data server, i.e., is a special stateid or has | with the data server, i.e., is a special stateid or has | |||
a non-zero seqid value. | a non-zero seqid value. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | <t> | |||
<t> | ||||
When a COMPOUND first executes an operation from class 3 above, | When a COMPOUND first executes an operation from class 3 above, | |||
it acts as a normal COMPOUND on any other server, and the | it acts as a normal COMPOUND on any other server, and the | |||
data-server personality ceases to be relevant. | data-server personality ceases to be relevant. | |||
There are no special restrictions on the | There are no special restrictions on the | |||
operations in the COMPOUND to limit them to those for | operations in the COMPOUND to limit them to those for | |||
a data server. When a PUTFH is done, filehandles | a data server. When a PUTFH is done, filehandles | |||
derived from the layout are not valid. If their format | derived from the layout are not valid. If their format | |||
is not normally acceptable, then NFS4ERR_BADHANDLE MUST | is not normally acceptable, then NFS4ERR_BADHANDLE <bcp14>MUST</bcp14> | |||
result. Similarly, current filehandles for other operations | result. Similarly, current filehandles for other operations | |||
do not accept filehandles derived from layouts and are not | do not accept filehandles derived from layouts and are not | |||
normally usable on the metadata server. Using these | normally usable on the metadata server. Using these | |||
will result in NFS4ERR_STALE. | will result in NFS4ERR_STALE. | |||
</t> | </t> | |||
<t> | <t> | |||
When a COMPOUND first executes an operation from class 2, | When a COMPOUND first executes an operation from class 2, | |||
which would be PUTFH where the filehandle | which would be PUTFH where the filehandle | |||
is one from a layout, the COMPOUND henceforth is interpreted | is one from a layout, the COMPOUND henceforth is interpreted | |||
with respect to the data-server personality. | with respect to the data-server personality. | |||
Operations outside the two classes discussed | Operations outside the two classes discussed | |||
above MUST result in NFS4ERR_NOTSUPP. Filehandles | above <bcp14>MUST</bcp14> result in NFS4ERR_NOTSUPP. Filehandles | |||
are validated using the rules of the data server, | are validated using the rules of the data server, | |||
resulting in NFS4ERR_BADHANDLE and/or NFS4ERR_STALE | resulting in NFS4ERR_BADHANDLE and/or NFS4ERR_STALE | |||
even when they would not normally do so when addressed | even when they would not normally do so when addressed | |||
to the non-data-server personality. Stateids must obey | to the non-data-server personality. Stateids must obey | |||
the rules of the data server in that any use of special | the rules of the data server in that any use of special | |||
stateids or stateids with non-zero seqid values must | stateids or stateids with non-zero seqid values must | |||
result in NFS4ERR_BAD_STATEID. | result in NFS4ERR_BAD_STATEID. | |||
</t> | </t> | |||
<t> | <t> | |||
Until the server first executes an operation from class 2 | Until the server first executes an operation from class 2 | |||
or class 3, the client MUST NOT depend on the operation | or class 3, the client <bcp14>MUST NOT</bcp14> depend on the operation | |||
being executed by either the data-server or the non-data-server | being executed by either the data-server or the non-data-server | |||
personality. The server MUST pick one personality consistently | personality. The server <bcp14>MUST</bcp14> pick one personality consistently | |||
for a given COMPOUND, with the only possible transition being | for a given COMPOUND, with the only possible transition being | |||
a single one when the first operation from class 2 or class 3 | a single one when the first operation from class 2 or class 3 | |||
is executed. | is executed. | |||
</t> | </t> | |||
<t> | <t> | |||
Because of the complexity induced by assigning filehandles so | Because of the complexity induced by assigning filehandles so | |||
they can be used on both a data server and a metadata server, it | they can be used on both a data server and a metadata server, it | |||
is RECOMMENDED that where the same server can have both | is <bcp14>RECOMMENDED</bcp14> that where the same server can have both | |||
personalities, the server assign separate unique filehandles | personalities, the server assign separate unique filehandles | |||
to both personalities. This makes it unambiguous for which server | to both personalities. This makes it unambiguous for which server | |||
a given request is intended. | a given request is intended. | |||
</t> | </t> | |||
<t> | <t> | |||
GETATTR and SETATTR MUST be directed to the metadata | GETATTR and SETATTR <bcp14>MUST</bcp14> be directed to the metadata | |||
server. In the case of a SETATTR of the size attribute, | server. In the case of a SETATTR of the size attribute, | |||
the control protocol is responsible for propagating size | the control protocol is responsible for propagating size | |||
updates/truncations to the data servers. In the case of | updates/truncations to the data servers. In the case of | |||
extending WRITEs to the data servers, the new size must | extending WRITEs to the data servers, the new size must | |||
be visible on the metadata server once a LAYOUTCOMMIT | be visible on the metadata server once a LAYOUTCOMMIT | |||
has completed (see <xref target="general_layoutcommit" | has completed (see <xref target="general_layoutcommit" format="default"/>). <x | |||
/>). <xref target="component_file_size" /> describes the | ref target="component_file_size" format="default"/> describes the | |||
mechanism by which the client is to handle data-server | mechanism by which the client is to handle data-server | |||
files that do not reflect the metadata server's size. | files that do not reflect the metadata server's size. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="commit_thru_mds" numbered="true" toc="default"> | ||||
<section title="COMMIT through Metadata Server" anchor="commit_thru_mds"> | <name>COMMIT through Metadata Server</name> | |||
<t> | <t> | |||
The file layout provides two alternate means of providing for the | The file layout provides two alternate means of providing for the | |||
commit of data written through data servers. The flag | commit of data written through data servers. The flag | |||
NFL4_UFLG_COMMIT_THRU_MDS in the field nfl_util of the file layout | NFL4_UFLG_COMMIT_THRU_MDS in the field nfl_util of the file layout | |||
(data type nfsv4_1_file_layout4) | (data type nfsv4_1_file_layout4) | |||
is an indication | is an indication | |||
from the metadata server to the client of the REQUIRED way of | from the metadata server to the client of the <bcp14>REQUIRED</bcp14> way of | |||
performing COMMIT, either by sending the COMMIT to the data server | performing COMMIT, either by sending the COMMIT to the data server | |||
or the metadata server. These two methods of dealing with the issue | or the metadata server. These two methods of dealing with the issue | |||
correspond to broad styles of implementation for a pNFS server | correspond to broad styles of implementation for a pNFS server | |||
supporting the file layout type. | supporting the file layout type. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
When the flag is FALSE, COMMIT operations MUST to be sent | <li> | |||
When the flag is FALSE, COMMIT operations <bcp14>MUST</bcp14> to be sent | ||||
to the data server to which the corresponding WRITE operations were | to the data server to which the corresponding WRITE operations were | |||
sent. This approach | sent. This approach | |||
is sometimes useful when file striping is implemented within the | is sometimes useful when file striping is implemented within the | |||
pNFS server (instead of the file system), | pNFS server (instead of the file system), | |||
with the individual data servers each implementing | with the individual data servers each implementing | |||
their own file systems. | their own file systems. | |||
</t> | </li> | |||
<t> | <li> | |||
When the flag is TRUE, COMMIT operations MUST be sent to the | <t> | |||
When the flag is TRUE, COMMIT operations <bcp14>MUST</bcp14> be sent to t | ||||
he | ||||
metadata server, rather than to the individual data servers. | metadata server, rather than to the individual data servers. | |||
This approach is sometimes useful when file striping | This approach is sometimes useful when file striping | |||
is implemented within the clustered file system that is the backend | is implemented within the clustered file system that is the backend | |||
to the pNFS server. In such | to the pNFS server. In such | |||
an implementation, each COMMIT to each | an implementation, each COMMIT to each | |||
data server might result in repeated writes of metadata | data server might result in repeated writes of metadata | |||
blocks to the | blocks to the | |||
detriment of write performance. Sending a single COMMIT | detriment of write performance. Sending a single COMMIT | |||
to the metadata server can be more efficient | to the metadata server can be more efficient | |||
when there exists a clustered file | when there exists a clustered file | |||
system capable of implementing such a coordinated COMMIT. | system capable of implementing such a coordinated COMMIT. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
If nfl_util & NFL4_UFLG_COMMIT_THRU_MDS is TRUE, | If nfl_util & NFL4_UFLG_COMMIT_THRU_MDS is TRUE, | |||
then in order to maintain the current NFSv4.1 commit and | then in order to maintain the current NFSv4.1 commit and | |||
recovery model, the data servers MUST return a common | recovery model, the data servers <bcp14>MUST</bcp14> return a common | |||
writeverf verifier in all WRITE responses for a given file | writeverf verifier in all WRITE responses for a given file | |||
layout, and the metadata server's COMMIT implementation | layout, and the metadata server's COMMIT implementation | |||
must return the same writeverf. The value of the | must return the same writeverf. The value of the | |||
writeverf verifier MUST be changed at the metadata server | writeverf verifier <bcp14>MUST</bcp14> be changed at the metadata server | |||
or any data server that is referenced in the layout, | or any data server that is referenced in the layout, | |||
whenever there is a server event that can possibly lead to | whenever there is a server event that can possibly lead to | |||
loss of uncommitted data. The scope of the verifier can | loss of uncommitted data. The scope of the verifier can | |||
be for a file or for the entire pNFS server. It might be | be for a file or for the entire pNFS server. It might be | |||
more difficult for the server to maintain the verifier | more difficult for the server to maintain the verifier | |||
at the file level, but the benefit is that only events | at the file level, but the benefit is that only events | |||
that impact a given file will require recovery action. | that impact a given file will require recovery action. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ul> | |||
<t> | <t> | |||
Note that if the layout specified dense packing, then the | Note that if the layout specified dense packing, then the | |||
offset used to a COMMIT to the MDS may differ than that of | offset used to a COMMIT to the MDS may differ than that of | |||
an offset used to a COMMIT to the data server. | an offset used to a COMMIT to the data server. | |||
</t> | </t> | |||
<t> | <t> | |||
The single COMMIT to the metadata server will return a verifier, and | The single COMMIT to the metadata server will return a verifier, and | |||
the client should compare it to all the verifiers from the WRITEs and | the client should compare it to all the verifiers from the WRITEs and | |||
fail the COMMIT if there are any mismatched verifiers. If COMMIT to the | fail the COMMIT if there are any mismatched verifiers. If COMMIT to the | |||
metadata server fails, the client should re-send WRITEs for all the | metadata server fails, the client should re-send WRITEs for all the | |||
modified data in the file. The client should treat modified data with | modified data in the file. The client should treat modified data with | |||
a mismatched verifier | a mismatched verifier | |||
as a WRITE failure and try to recover by resending the WRITEs to the | as a WRITE failure and try to recover by resending the WRITEs to the | |||
original data server or using another path to that data if the layout | original data server or using another path to that data if the layout | |||
has not been recalled. Alternatively, the client can obtain | has not been recalled. Alternatively, the client can obtain | |||
a new layout or it could rewrite the data directly to the metadata server. If | a new layout or it could rewrite the data directly to the metadata server. If | |||
nfl_util & NFL4_UFLG_COMMIT_THRU_MDS is FALSE, sending | nfl_util & NFL4_UFLG_COMMIT_THRU_MDS is FALSE, sending | |||
a COMMIT to the metadata server might have no effect. If | a COMMIT to the metadata server might have no effect. If | |||
nfl_util & NFL4_UFLG_COMMIT_THRU_MDS is FALSE, a COMMIT | nfl_util & NFL4_UFLG_COMMIT_THRU_MDS is FALSE, a COMMIT | |||
sent to the metadata server should be used only to commit data that | sent to the metadata server should be used only to commit data that | |||
was written to the metadata server. See <xref target="storage_device_recovery" /> | was written to the metadata server. See <xref target="storage_device_recovery" format="default"/> | |||
for recovery options. | for recovery options. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="The Layout Iomode"> | <name>The Layout Iomode</name> | |||
<t> | <t> | |||
The layout iomode need not be used by the metadata server when | The layout iomode need not be used by the metadata server when | |||
servicing NFSv4.1 file-based layouts, although in some circumstances | servicing NFSv4.1 file-based layouts, although in some circumstances | |||
it may be useful. For example, if the server implementation | it may be useful. For example, if the server implementation | |||
supports reading from read-only replicas or mirrors, it would be | supports reading from read-only replicas or mirrors, it would be | |||
useful for the server to return a layout enabling the client to do | useful for the server to return a layout enabling the client to do | |||
so. As such, the client SHOULD set the iomode based on its intent | so. As such, the client <bcp14>SHOULD</bcp14> set the iomode based on its int ent | |||
to read or write the data. The client may default to an iomode of | to read or write the data. The client may default to an iomode of | |||
LAYOUTIOMODE4_RW. The iomode need not be checked by the | LAYOUTIOMODE4_RW. The iomode need not be checked by the | |||
data servers when clients perform I/O. However, the data servers | data servers when clients perform I/O. However, the data servers | |||
SHOULD still validate that the client holds a valid layout | <bcp14>SHOULD</bcp14> still validate that the client holds a valid layout | |||
and return an error if the client does not. | and return an error if the client does not. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="Metadata and Data Server State Coordination"> | <name>Metadata and Data Server State Coordination</name> | |||
<section anchor="global_stateid" numbered="true" toc="default"> | ||||
<section title="Global Stateid Requirements" anchor="global_stateid"> | <name>Global Stateid Requirements</name> | |||
<t> | <t> | |||
When the client sends | When the client sends | |||
I/O to a data server, the stateid used MUST NOT be a layout stateid | I/O to a data server, the stateid used <bcp14>MUST NOT</bcp14> be a layout sta teid | |||
as returned by LAYOUTGET or sent by CB_LAYOUTRECALL. | as returned by LAYOUTGET or sent by CB_LAYOUTRECALL. | |||
Permitted stateids are based on one of the following: | Permitted stateids are based on one of the following: | |||
an OPEN stateid | an OPEN stateid | |||
(the stateid field of data type OPEN4resok as returned by OPEN), | (the stateid field of data type OPEN4resok as returned by OPEN), | |||
a delegation stateid (the stateid field of data types open_read_delegation4 | a delegation stateid (the stateid field of data types open_read_delegation4 | |||
and open_write_delegation4 as returned by OPEN or WANT_DELEGATION, | and open_write_delegation4 as returned by OPEN or WANT_DELEGATION, | |||
or as sent by CB_PUSH_DELEG), or a stateid returned by the LOCK or LOCKU | or as sent by CB_PUSH_DELEG), or a stateid returned by the LOCK or LOCKU | |||
operations. The stateid sent to the data server MUST be sent with | operations. The stateid sent to the data server <bcp14>MUST</bcp14> be sent w ith | |||
the seqid set to zero, indicating the most current version of that | the seqid set to zero, indicating the most current version of that | |||
stateid, rather than indicating a specific non-zero seqid value. In | stateid, rather than indicating a specific non-zero seqid value. In | |||
no case is the use of special stateid values allowed. | no case is the use of special stateid values allowed. | |||
</t> | </t> | |||
<t> | <t> | |||
The stateid used for I/O MUST have the same | The stateid used for I/O <bcp14>MUST</bcp14> have the same | |||
effect and be subject to the same validation on a data server as it | effect and be subject to the same validation on a data server as it | |||
would if the I/O was being performed on the metadata server itself | would if the I/O was being performed on the metadata server itself | |||
in the absence of pNFS. This has the implication that stateids are | in the absence of pNFS. This has the implication that stateids are | |||
globally valid on both the metadata and data servers. This | globally valid on both the metadata and data servers. This | |||
requires the metadata server to propagate changes in LOCK and OPEN | requires the metadata server to propagate changes in LOCK and OPEN | |||
state to the data servers, so that the data servers can | state to the data servers, so that the data servers can | |||
validate I/O accesses. This is discussed further in <xref | validate I/O accesses. This is discussed further in <xref target="state_propag | |||
target="state_propagation" />. Depending on when stateids are | ation" format="default"/>. Depending on when stateids are | |||
propagated, the existence of a valid stateid on the data server | propagated, the existence of a valid stateid on the data server | |||
may act as proof of a valid layout. | may act as proof of a valid layout. | |||
</t> | </t> | |||
<t> | <t> | |||
Clients performing I/O operations need to select an appropriate | Clients performing I/O operations need to select an appropriate | |||
stateid based on the | 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 | the various types of state-owners sending the I/O requests. The | |||
rules for doing so when referencing data servers are somewhat | rules for doing so when referencing data servers are somewhat | |||
different from those discussed in <xref target="stateid_use" />, | different from those discussed in <xref target="stateid_use" format="d efault"/>, | |||
which apply when accessing metadata servers. | which apply when accessing metadata servers. | |||
</t> | </t> | |||
<t> | <t> | |||
The following rules, applied in order of decreasing priority, govern | The following rules, applied in order of decreasing priority, govern | |||
the selection of the appropriate stateid: | the selection of the appropriate stateid: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If the client holds a delegation for the file in question, the | If the client holds a delegation for the file in question, the | |||
delegation stateid should be used. | delegation stateid should be used. | |||
</t> | </li> | |||
<t> | <li> | |||
Otherwise, there must be an OPEN stateid for the current | Otherwise, there must be an OPEN stateid for the current | |||
open-owner, and that | open-owner, and that | |||
OPEN stateid for the open file in question is used, unless | OPEN stateid for the open file in question is used, unless | |||
mandatory locking prevents that. See below. | mandatory locking prevents that. See below. | |||
</t> | </li> | |||
<t> | <li> | |||
If the data server had previously responded with NFS4ERR_LOCKED | If the data server had previously responded with NFS4ERR_LOCKED | |||
to use of the OPEN stateid, then the client should use the | to use of the OPEN stateid, then the client should use the | |||
byte-range lock stateid whenever one exists for that open file | byte-range lock stateid whenever one exists for that open file | |||
with the current lock-owner. | with the current lock-owner. | |||
</t> | </li> | |||
<t> | <li> | |||
Special stateids should never be used. If they are used, the data | Special stateids should never be used. If they are used, the data | |||
server MUST reject the I/O with an NFS4ERR_BAD_STATEID error. | server <bcp14>MUST</bcp14> reject the I/O with an NFS4ERR_BAD_STAT | |||
</t> | EID error. | |||
</list> | </li> | |||
</t> | </ul> | |||
</section> | </section> | |||
<section anchor="state_propagation" numbered="true" toc="default"> | ||||
<section title="Data Server State Propagation" anchor="state_propagation" > | <name>Data Server State Propagation</name> | |||
<t> | <t> | |||
Since the metadata server, which handles byte-range lock and | Since the metadata server, which handles byte-range lock and | |||
open-mode state changes as well as ACLs, might not be | open-mode state changes as well as ACLs, might not be | |||
co-located with the data servers where I/O accesses | co-located with the data servers where I/O accesses | |||
are validated, the server implementation MUST take | are validated, the server implementation <bcp14>MUST</bcp14> take | |||
care of propagating changes of this state to the data | care of propagating changes of this state to the data | |||
servers. Once the propagation to the data servers is | servers. Once the propagation to the data servers is | |||
complete, the full effect of those changes MUST be in | complete, the full effect of those changes <bcp14>MUST</bcp14> be in | |||
effect at the data servers. However, some state changes | effect at the data servers. However, some state changes | |||
need not be propagated immediately, although all changes | need not be propagated immediately, although all changes | |||
SHOULD be propagated promptly. These state propagations | <bcp14>SHOULD</bcp14> be propagated promptly. These state propagations | |||
have an impact on the design of the control protocol, | have an impact on the design of the control protocol, | |||
even though the control protocol is outside of the scope | even though the control protocol is outside of the scope | |||
of this specification. Immediate propagation refers to | of this specification. Immediate propagation refers to | |||
the synchronous propagation of state from the metadata | the synchronous propagation of state from the metadata | |||
server to the data server(s); the propagation must be | server to the data server(s); the propagation must be | |||
complete before returning to the client. | complete before returning to the client. | |||
</t> | </t> | |||
<section numbered="true" toc="default"> | ||||
<section title="Lock State Propagation"> | <name>Lock State Propagation</name> | |||
<t> | <t> | |||
If the pNFS server supports mandatory byte-range locking, any mandatory byte-r ange locks | If the pNFS server supports mandatory byte-range locking, any mandatory byte-r ange locks | |||
on a file MUST be made effective at the data servers before | on a file <bcp14>MUST</bcp14> be made effective at the data servers before | |||
the request that establishes them returns to the caller. The | the request that establishes them returns to the caller. The | |||
effect MUST be the same as if the mandatory byte-range lock state were | effect <bcp14>MUST</bcp14> be the same as if the mandatory byte-range lock sta te were | |||
synchronously propagated to the data servers, even though the | synchronously propagated to the data servers, even though the | |||
details of the control protocol may avoid actual transfer of the | details of the control protocol may avoid actual transfer of the | |||
state under certain circumstances. | state under certain circumstances. | |||
</t> | </t> | |||
<t> | <t> | |||
On the other hand, since | On the other hand, since | |||
advisory byte-range lock state is not used for checking I/O accesses at | advisory byte-range lock state is not used for checking I/O accesses at | |||
the data servers, there is no semantic reason for propagating | the data servers, there is no semantic reason for propagating | |||
advisory byte-range lock state to the data servers. | advisory byte-range lock state to the data servers. | |||
Since updates to advisory locks neither confer nor remove | Since updates to advisory locks neither confer nor remove | |||
privileges, these changes need not be propagated immediately, and | privileges, these changes need not be propagated immediately, and | |||
may not need to be propagated promptly. The updates to advisory | may not need to be propagated promptly. The updates to advisory | |||
locks need only be propagated when the data server needs to | locks need only be propagated when the data server needs to | |||
resolve a question about a stateid. In fact, if byte-range locking | resolve a question about a stateid. In fact, if byte-range locking | |||
is not mandatory (i.e., is advisory) the clients are advised to avoid | is not mandatory (i.e., is advisory) the clients are advised to avoid | |||
using the byte-range lock-based stateids for I/O. The stateids returned by | using the byte-range lock-based stateids for I/O. The stateids returned by | |||
OPEN are sufficient and eliminate overhead for this kind of state | OPEN are sufficient and eliminate overhead for this kind of state | |||
propagation. | propagation. | |||
</t> | </t> | |||
<t> | <t> | |||
If a client gets back an NFS4ERR_LOCKED error from a | If a client gets back an NFS4ERR_LOCKED error from a | |||
data server, this is an indication that mandatory byte-range | data server, this is an indication that mandatory byte-range | |||
locking is in force. The client recovers from this by | locking is in force. The client recovers from this by | |||
getting a byte-range lock that covers the affected range | getting a byte-range lock that covers the affected range | |||
and re-sends the I/O with the stateid of the byte-range lock. | and re-sends the I/O with the stateid of the byte-range lock. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section numbered="true" toc="default"> | |||
<name>Open and Deny Mode Validation</name> | ||||
<section title="Open and Deny Mode Validation"> | <t> | |||
<t> | Open and deny mode validation <bcp14>MUST</bcp14> be performed against | |||
Open and deny mode validation MUST be performed against | ||||
the open and deny mode(s) held by the data servers. When | the open and deny mode(s) held by the data servers. When | |||
access is reduced or a deny mode made more restrictive | access is reduced or a deny mode made more restrictive | |||
(because of CLOSE or OPEN_DOWNGRADE), the data server MUST | (because of CLOSE or OPEN_DOWNGRADE), the data server <bcp14>MUST</bcp14> | |||
prevent any I/Os that would be denied if performed on the | prevent any I/Os that would be denied if performed on the | |||
metadata server. When access is expanded, | metadata server. When access is expanded, | |||
the data server MUST make sure that no requests are | the data server <bcp14>MUST</bcp14> make sure that no requests are | |||
subsequently rejected because of | subsequently rejected because of | |||
open or deny issues that no longer apply, given the | open or deny issues that no longer apply, given the | |||
previous relaxation. | previous relaxation. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="File Attributes"> | <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 t | that the metadata is synchronized with changes made to the data servers. | |||
he NFSv4.1-based data storage protocol, | 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" /> 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> | |||
<t> | <t> | |||
Any changes to file attributes that control authorization or | Any changes to file attributes that control authorization or | |||
access as reflected by ACCESS calls or READs and WRITEs on the | access as reflected by ACCESS calls or READs and WRITEs on the | |||
metadata server, MUST be propagated to the data servers for | metadata server, <bcp14>MUST</bcp14> be propagated to the data servers for | |||
enforcement on READ and WRITE I/O calls. If the changes made on the | enforcement on READ and WRITE I/O calls. If the changes made on the | |||
metadata server result in more restrictive access permissions for | metadata server result in more restrictive access permissions for | |||
any user, those changes MUST be propagated to the data servers | any user, those changes <bcp14>MUST</bcp14> be propagated to the data servers | |||
synchronously. | synchronously. | |||
</t> | </t> | |||
<t> | <t> | |||
The OPEN operation (<xref target="OP_OPEN_IMPLEMENTATION" | The OPEN operation (<xref target="OP_OPEN_IMPLEMENTATION" format="default"/>) | |||
/>) does not impose any requirement that I/O operations | does not impose any requirement that I/O operations | |||
on an open file have the same credentials as the OPEN | on an open file have the same credentials as the OPEN | |||
itself (unless EXCHGID4_FLAG_BIND_PRINC_STATEID is | itself (unless EXCHGID4_FLAG_BIND_PRINC_STATEID is | |||
set when EXCHANGE_ID creates the client ID), and so it | set when EXCHANGE_ID creates the client ID), and so it | |||
requires the server's READ and WRITE operations to | requires the server's READ and WRITE operations to | |||
perform appropriate access checking. Changes to ACLs | perform appropriate access checking. Changes to ACLs | |||
also require new access checking by READ and WRITE on | also require new access checking by READ and WRITE on | |||
the server. The propagation of access-right changes due | the server. The propagation of access-right changes due | |||
to changes in ACLs may be asynchronous only if the server | to changes in ACLs may be asynchronous only if the server | |||
implementation is able to determine that the updated | implementation is able to determine that the updated | |||
ACL is not more restrictive for any user specified in | ACL is not more restrictive for any user specified in | |||
the old ACL. Due to the relative infrequency of ACL | the old ACL. Due to the relative infrequency of ACL | |||
updates, it is suggested that all changes be propagated | updates, it is suggested that all changes be propagated | |||
synchronously. | synchronously. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="component_file_size" numbered="true" toc="default"> | ||||
<section title="Data Server Component File Size" | <name>Data Server Component File Size</name> | |||
anchor="component_file_size"> | <t> | |||
<t> | ||||
A potential problem exists when a component data file on a | A potential problem exists when a component data file on a | |||
particular data server has grown past EOF; the problem exists for | particular data server has grown past EOF; the problem exists for | |||
both dense and sparse layouts. Imagine the following scenario: a | both dense and sparse layouts. Imagine the following scenario: a | |||
client creates a new file (size == 0) and writes to byte 131072; the | client creates a new file (size == 0) and writes to byte 131072; the | |||
client then seeks to the beginning of the file and reads byte 100. | client then seeks to the beginning of the file and reads byte 100. | |||
The client should receive zeroes back as a result of the READ. However, | The client should receive zeroes back as a result of the READ. However, | |||
if the striping pattern directs the client to send the READ to | if the striping pattern directs the client to send the READ to | |||
a data server other than the one that received the | a data server other than the one that received the | |||
client's original WRITE, the data server servicing the READ may | client's original WRITE, the data server servicing the READ may | |||
believe that the file's size is still 0 bytes. In that event, the | believe that the file's size is still 0 bytes. In that event, the | |||
data server's READ response will contain zero bytes and an | data server's READ response will contain zero bytes and an | |||
indication of EOF. The data server can only return zeroes if it knows that | indication of EOF. The data server can only return zeroes if it knows that | |||
the file's size has been extended. This would require the immediate | the file's size has been extended. This would require the immediate | |||
propagation of the file's size to all data servers, which is | propagation of the file's size to all data servers, which is | |||
potentially very costly. Therefore, the client that has | potentially very costly. Therefore, the client that has | |||
initiated the extension of the file's size MUST be prepared to deal | initiated the extension of the file's size <bcp14>MUST</bcp14> be prepared to deal | |||
with these EOF conditions. | with these EOF conditions. | |||
When the offset in the arguments to READ | When the offset in the arguments to READ | |||
is less than the client's view of the file size, if the READ response | is less than the client's view of the file size, if the READ response | |||
indicates EOF and/or contains fewer bytes than requested, the client | indicates EOF and/or contains fewer bytes than requested, the client | |||
will interpret such a response as a hole in the file, and the | will interpret such a response as a hole in the file, and the | |||
NFS client will substitute zeroes for the data. | NFS client will substitute zeroes for the data. | |||
</t> | </t> | |||
<t> | <t> | |||
The NFSv4.1 protocol only provides close-to-open file data cache | The NFSv4.1 protocol only provides close-to-open file data cache | |||
semantics; meaning that when the file is closed, all modified data is | semantics; meaning that when the file is closed, all modified data is | |||
written to the server. When a subsequent OPEN of the file is | written to the server. When a subsequent OPEN of the file is | |||
done, the change attribute is inspected for a difference from a | done, the change attribute is inspected for a difference from a | |||
cached value for the change attribute. For the case above, this means | cached value for the change attribute. For the case above, this means | |||
that a LAYOUTCOMMIT will be done at close (along with the data | that a LAYOUTCOMMIT will be done at close (along with the data | |||
WRITEs) and will update the file's size and change attribute. Access | WRITEs) and will update the file's size and change attribute. Access | |||
from another client after that point will result in the appropriate | from another client after that point will result in the appropriate | |||
size being returned. | size being returned. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="file_layout_revoke" numbered="true" toc="default"> | ||||
<section title="Layout Revocation and Fencing" anchor="file_layout_revoke" > | <name>Layout Revocation and Fencing</name> | |||
<t> | <t> | |||
As described in <xref target="crash_recovery" />, the | As described in <xref target="crash_recovery" format="default"/>, the | |||
layout-type-specific storage protocol is responsible | layout-type-specific storage protocol is responsible | |||
for handling the effects of I/Os that started before | for handling the effects of I/Os that started before | |||
lease expiration and extend through lease expiration. | lease expiration and extend through lease expiration. | |||
The LAYOUT4_NFSV4_1_FILES layout type | The LAYOUT4_NFSV4_1_FILES layout type | |||
can prevent all I/Os to data servers from | can prevent all I/Os to data servers from | |||
being executed after lease expiration (this prevention is | being executed after lease expiration (this prevention is | |||
called "fencing"), without relying | called "fencing"), without relying | |||
on a precise client lease timer and without requiring | on a precise client lease timer and without requiring | |||
data servers to maintain lease timers. The | data servers to maintain lease timers. The | |||
LAYOUT4_NFSV4_1_FILES pNFS server has the flexibility to | LAYOUT4_NFSV4_1_FILES pNFS server has the flexibility to | |||
revoke individual layouts, and thus fence I/O on a per-file | revoke individual layouts, and thus fence I/O on a per-file | |||
basis. | basis. | |||
</t> | </t> | |||
<t> | <t> | |||
In addition to lease expiration, | In addition to lease expiration, | |||
the reasons a layout can be revoked include: client fails to respond to | the reasons a layout can be revoked include: client fails to respond to | |||
a CB_LAYOUTRECALL, | a CB_LAYOUTRECALL, | |||
the | the | |||
metadata server restarts, or administrative intervention. Regardless | metadata server restarts, or administrative intervention. Regardless | |||
of the reason, once a client's layout has been revoked, the pNFS | of the reason, once a client's layout has been revoked, the pNFS | |||
server MUST prevent the client from sending I/O for the affected file | server <bcp14>MUST</bcp14> prevent the client from sending I/O for the affecte | |||
from and to all data servers; in other words, it MUST fence the | d file | |||
from and to all data servers; in other words, it <bcp14>MUST</bcp14> fence the | ||||
client from the affected file on the data servers. | client from the affected file on the data servers. | |||
</t> | </t> | |||
<t> | <t> | |||
Fencing works as follows. As described in <xref | Fencing works as follows. As described in <xref target="pnfs_session_stuff" fo | |||
target="pnfs_session_stuff" />, in COMPOUND procedure | rmat="default"/>, in COMPOUND procedure | |||
requests to the data server, the data filehandle provided | requests to the data server, the data filehandle provided | |||
by the PUTFH operation and the stateid in the READ or | by the PUTFH operation and the stateid in the READ or | |||
WRITE operation are used to ensure that the client has | WRITE operation are used to ensure that the client has | |||
a valid layout for the I/O being performed; if it does | a valid layout for the I/O being performed; if it does | |||
not, the I/O is rejected with NFS4ERR_PNFS_NO_LAYOUT. | not, the I/O is rejected with NFS4ERR_PNFS_NO_LAYOUT. | |||
The server can simply check the stateid and, additionally, | The server can simply check the stateid and, additionally, | |||
make the data filehandle stale if the layout specified | make the data filehandle stale if the layout specified | |||
a data filehandle that is different from the metadata server's | a data filehandle that is different from the metadata server's | |||
filehandle for the file (see the nfl_fh_list description in | filehandle for the file (see the nfl_fh_list description in | |||
<xref target="file_data_types" />). | <xref target="file_data_types" format="default"/>). | |||
</t> | </t> | |||
<t> | <t> | |||
Before the metadata server takes any action to revoke | Before the metadata server takes any action to revoke | |||
layout state given out by a previous instance, it must make | layout state given out by a previous instance, it must make | |||
sure that all layout state from that previous instance are | sure that all layout state from that previous instance are | |||
invalidated at the data servers. This has the following | invalidated at the data servers. This has the following | |||
implications. | implications. | |||
<list style='symbols'> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <li> | |||
The metadata server must not restripe a | The metadata server must not restripe a | |||
file until it has contacted all of the data servers | file until it has contacted all of the data servers | |||
to invalidate the layouts from the previous instance. | to invalidate the layouts from the previous instance. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
The metadata server must not give out mandatory locks that conflict with | The metadata server must not give out mandatory locks that conflict with | |||
layouts from the previous instance without either doing | layouts from the previous instance without either doing | |||
a specific layout invalidation (as it would have to do anyway) | a specific layout invalidation (as it would have to do anyway) | |||
or doing a global data server invalidation. | or doing a global data server invalidation. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
<section anchor="file_security_considerations" numbered="true" toc="defaul | ||||
</section> | t"> | |||
<name>Security Considerations for the File Layout Type</name> | ||||
<section title="Security Considerations for the File Layout Type" anchor="file_s | <t> | |||
ecurity_considerations"> | The NFSv4.1 file layout type <bcp14>MUST</bcp14> adhere to the security | |||
<t> | considerations outlined in <xref target="security_considerations_pnfs" format= | |||
The NFSv4.1 file layout type MUST adhere to the security | "default"/>. NFSv4.1 data servers <bcp14>MUST</bcp14> make all of the | |||
considerations outlined in <xref target="security_considerations_pnfs" | ||||
/>. NFSv4.1 data servers MUST make all of the | ||||
required access checks on each READ or WRITE I/O as determined by | required access checks on each READ or WRITE I/O as determined by | |||
the NFSv4.1 protocol. | the NFSv4.1 protocol. | |||
If the metadata server would deny a READ or WRITE | If the metadata server would deny a READ or WRITE | |||
operation on a file due to its ACL, mode attribute, open | operation on a file due to its ACL, mode attribute, open | |||
access mode, open deny mode, mandatory byte-range lock state, or any other | access mode, open deny mode, mandatory byte-range lock state, or any other | |||
attributes and state, the data server MUST also deny the | attributes and state, the data server <bcp14>MUST</bcp14> also deny the | |||
READ or WRITE operation. This impacts the control | READ or WRITE operation. This impacts the control | |||
protocol and the propagation of state from the metadata | protocol and the propagation of state from the metadata | |||
server to the data servers; see <xref | server to the data servers; see <xref target="state_propagation" format="defau | |||
target="state_propagation" /> for more details. | lt"/> for more details. | |||
</t> | </t> | |||
<t> | <t> | |||
The methods for authentication, | The methods for authentication, | |||
integrity, and privacy for data servers based on the | integrity, and privacy for data servers based on the | |||
LAYOUT4_NFSV4_1_FILES layout type are the same as those used | LAYOUT4_NFSV4_1_FILES layout type are the same as those used | |||
by metadata servers. Metadata and data servers | by metadata servers. Metadata and data servers | |||
use ONC RPC security flavors to | use ONC RPC security flavors to | |||
authenticate, and SECINFO and SECINFO_NO_NAME | authenticate, and SECINFO and SECINFO_NO_NAME | |||
to negotiate the security mechanism and services | to negotiate the security mechanism and services | |||
to be used. Thus, when using the LAYOUT4_NFSV4_1_FILES layout type, | to be used. Thus, when using the LAYOUT4_NFSV4_1_FILES layout type, | |||
the impact on the RPC-based security | the impact on the RPC-based security | |||
model due to pNFS (as alluded to in Sections | model due to pNFS (as alluded to in Sections | |||
<xref target="rpc_and_security" format="counter"/> | <xref target="rpc_and_security" format="counter"/> | |||
and <xref target="parallel_access" format="counter"/>) is zero. | and <xref target="parallel_access" format="counter"/>) is zero. | |||
</t> | </t> | |||
<t> | <t> | |||
For a given file object, a metadata server | For a given file object, a metadata server | |||
MAY require different security parameters | <bcp14>MAY</bcp14> require different security parameters | |||
(secinfo4 value) than the data server. | (secinfo4 value) than the data server. | |||
For a given file object with multiple data servers, | For a given file object with multiple data servers, | |||
the secinfo4 value SHOULD be the same across | the secinfo4 value <bcp14>SHOULD</bcp14> be the same across | |||
all data servers. If the secinfo4 values across a metadata server | all data servers. If the secinfo4 values across a metadata server | |||
and its data servers differ for a specific file, the | and its data servers differ for a specific file, the | |||
mapping of the principal to the server's internal user identifier | mapping of the principal to the server's internal user identifier | |||
MUST be the same in order for the access-control checks based on | <bcp14>MUST</bcp14> be the same in order for the access-control checks based o n | |||
ACL, mode, open and deny mode, and mandatory locking to be | ACL, mode, open and deny mode, and mandatory locking to be | |||
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 MUST support the SECINFO_NO_NAME operation on both | implementation <bcp14>MUST</bcp14> support the SECINFO_NO_NAME operation on bo th | |||
the metadata and data servers. | the metadata and data servers. | |||
</t> | </t> | |||
</section> | ||||
</section> | </section> | |||
</section> | <section anchor="internationalization" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Internationalization</name> | |||
$ --> | <t> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | ||||
<!-- Copyright (C) The Internet Society (2006) --> | ||||
<section anchor="internationalization" title="Internationalization"> | ||||
<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">ISO10646</xref> allows for this type | by <xref target="ISO.10646-1.1993" format="default">ISO10646</xref> allows for t his type | |||
of access and follows the policy described in "IETF Policy on | of access and follows the policy described in "IETF Policy on | |||
Character Sets and Languages", <xref target="RFC2277">RFC 2277</xref>. | Character Sets and Languages", <xref target="RFC2277" format="default">RFC 2277< /xref>. | |||
</t> | </t> | |||
<t> | <t> | |||
<xref target="RFC3454">RFC 3454</xref>, otherwise known as "stringprep", documen | <xref target="RFC3454" format="default">RFC 3454</xref>, otherwise known as "str | |||
ts a | ingprep", documents a | |||
framework for using Unicode/UTF-8 in networking protocols so as "to | framework for using Unicode/UTF-8 in networking protocols so as "to | |||
increase the likelihood that string input and string comparison work | increase the likelihood that string input and string comparison work | |||
in ways that make sense for typical users throughout the world". A | in ways that make sense for typical users throughout the world". A | |||
protocol must define a profile of stringprep "in order to fully | protocol must define a profile of stringprep "in order to fully | |||
specify the processing options". The remainder of this | specify the processing options". The remainder of this | |||
section defines the NFSv4.1 stringprep profiles. Much of the terminology | section defines the NFSv4.1 stringprep profiles. Much of the terminology | |||
used for the remainder of this section comes from stringprep. | used for the remainder of this section comes from stringprep. | |||
</t> | </t> | |||
<t> | <t> | |||
There are three UTF-8 string types defined for NFSv4.1: | There are three UTF-8 string types defined for NFSv4.1: | |||
utf8str_cs, utf8str_cis, and utf8str_mixed. Separate profiles are | utf8str_cs, utf8str_cis, and utf8str_mixed. Separate profiles are | |||
defined for each. Each profile defines the following, as required by | defined for each. Each profile defines the following, as required by | |||
stringprep: | stringprep: | |||
<list style='symbols'> | ||||
<t> | ||||
The intended applicability of the profile. | ||||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The intended applicability of the profile. | ||||
</li> | ||||
<li> | ||||
The character repertoire that is the input and output to stringprep | The character repertoire that is the input and output to stringprep | |||
(which is Unicode 3.2 for the referenced version of stringprep). | (which is Unicode 3.2 for the referenced version of stringprep). | |||
However, NFSv4.1 implementations are not limited to 3.2. | However, NFSv4.1 implementations are not limited to 3.2. | |||
</t> | </li> | |||
<t> | <li> | |||
The mapping tables from stringprep used (as described in Section 3 of | The mapping tables from stringprep used (as described in Section | |||
stringprep). | <xref target="RFC3454" sectionFormat="bare" section="3"/> of stringprep). | |||
</t> | </li> | |||
<t> | <li> | |||
Any additional mapping tables specific to the profile. | Any additional mapping tables specific to the profile. | |||
</t> | </li> | |||
<t> | <li> | |||
The Unicode normalization used, if any (as described in Section 4 of stringprep) | The Unicode normalization used, if any (as described in Section | |||
. | <xref target="RFC3454" sectionFormat="bare" section="4"/> of stringprep). | |||
</t> | </li> | |||
<t> | <li> | |||
The tables from the stringprep listing of characters that are prohibited | The tables from the stringprep listing of characters that are prohibited | |||
as output (as described in Section 5 of stringprep). | as output (as described in Section <xref target="RFC3454" sectionFormat="bare" s | |||
</t> | ection="5"/> of stringprep). | |||
<t> | </li> | |||
The bidirectional string testing used, if any (as described in Section 6 of stri | <li> | |||
ngprep). | The bidirectional string testing used, if any (as described in Section <xref tar | |||
</t> | get="RFC3454" sectionFormat="bare" section="6"/> of stringprep). | |||
<t> | </li> | |||
<li> | ||||
Any additional characters that are prohibited as output specific to | Any additional characters that are prohibited as output specific to | |||
the profile. | the profile. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Stringprep discusses Unicode characters, whereas NFSv4.1 renders | Stringprep discusses Unicode characters, whereas NFSv4.1 renders | |||
UTF-8 characters. Since there is a one-to-one mapping from UTF-8 to | UTF-8 characters. Since there is a one-to-one mapping from UTF-8 to | |||
Unicode, when the remainder of this document refers to Unicode, | Unicode, when the remainder of this document refers to Unicode, | |||
the reader should assume UTF-8. | the reader should assume UTF-8. | |||
</t> | </t> | |||
<t> | <t> | |||
Much of the text for the profiles comes from <xref target="RFC3491">RFC 3491</xr | Much of the text for the profiles comes from RFC 3491 <xref target="RFC3491" for | |||
ef>. | mat="default"/>. | |||
</t> | </t> | |||
<section title="Stringprep Profile for the utf8str_cs Type"> | <section numbered="true" toc="default"> | |||
<t> | <name>Stringprep Profile for the utf8str_cs Type</name> | |||
<t> | ||||
Every use of the utf8str_cs type definition in the NFSv4 protocol specification follows the profile named | Every use of the utf8str_cs type definition in the NFSv4 protocol specification follows the profile named | |||
nfs4_cs_prep. | nfs4_cs_prep. | |||
</t> | </t> | |||
<section toc="exclude" title="Intended Applicability of the nfs4_cs_prep Profile | <section toc="exclude" numbered="true"> | |||
"> | <name>Intended Applicability of the nfs4_cs_prep Profile</name> | |||
<t> | <t> | |||
The utf8str_cs type is a case-sensitive string of UTF-8 characters. | The utf8str_cs type is a case-sensitive string of UTF-8 characters. | |||
Its primary use in NFSv4.1 is for naming components and | Its primary use in NFSv4.1 is for naming components and | |||
pathnames. Components and pathnames are stored on the server's | pathnames. Components and pathnames are stored on the server's | |||
file system. Two valid distinct UTF-8 strings might be the same after | file system. Two valid distinct UTF-8 strings might be the same after | |||
processing via the utf8str_cs profile. If the strings are two names | processing via the utf8str_cs profile. If the strings are two names | |||
inside a directory, the NFSv4.1 server will need to either: | inside a directory, the NFSv4.1 server will need to either: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
disallow the creation of a second name if its post-processed form | disallow the creation of a second name if its post-processed form | |||
collides with that of an existing name, or | collides with that of an existing name, or | |||
</t> | </li> | |||
<t> | <li> | |||
allow the creation of the second name, but arrange so that after | allow the creation of the second name, but arrange so that after | |||
post-processing, the second name is different than the post-processed | post-processing, the second name is different than the post-processed | |||
form of the first name. | form of the first name. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section toc="exclude" numbered="true"> | |||
<section toc="exclude" title="Character Repertoire of nfs4_cs_prep"> | <name>Character Repertoire of nfs4_cs_prep</name> | |||
<t> | <t> | |||
The nfs4_cs_prep profile uses Unicode 3.2, as defined in stringprep's | The nfs4_cs_prep profile uses Unicode 3.2, as defined in stringprep's | |||
Appendix A.1. | Appendix A.1. | |||
However, NFSv4.1 implementations are not limited to 3.2. | However, NFSv4.1 implementations are not limited to 3.2. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" title="Mapping Used by nfs4_cs_prep"> | <section toc="exclude" numbered="true"> | |||
<t> | <name>Mapping Used by nfs4_cs_prep</name> | |||
<t> | ||||
The nfs4_cs_prep profile specifies mapping using the | The nfs4_cs_prep profile specifies mapping using the | |||
following tables from stringprep: | following tables from stringprep: | |||
<list style='empty'> | ||||
<t> | ||||
Table B.1 | ||||
</t> | ||||
</list> | ||||
</t> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
Table B.1 | ||||
</li> | ||||
</ul> | ||||
<t> | ||||
Table B.2 is normally not part of the nfs4_cs_prep profile as it is | Table B.2 is normally not part of the nfs4_cs_prep profile as it is | |||
primarily for dealing with case-insensitive comparisons. However, if | primarily for dealing with case-insensitive comparisons. However, if | |||
the NFSv4.1 file server supports the case_insensitive file system | the NFSv4.1 file server supports the case_insensitive file system | |||
attribute, and if case_insensitive is TRUE, the NFSv4.1 server | attribute, and if case_insensitive is TRUE, the NFSv4.1 server | |||
MUST use Table B.2 (in addition to Table B1) when processing | <bcp14>MUST</bcp14> use Table B.2 (in addition to Table B1) when processing | |||
utf8str_cs strings, and the NFSv4.1 client MUST assume Table B.2 | utf8str_cs strings, and the NFSv4.1 client <bcp14>MUST</bcp14> assume Table B.2 | |||
(in addition to Table B.1) is being used. | (in addition to Table B.1) is being used. | |||
</t> | </t> | |||
<t> | <t> | |||
If the case_preserving attribute is present and set to FALSE, then the | If the case_preserving attribute is present and set to FALSE, then the | |||
NFSv4.1 server MUST use Table B.2 to map case when processing | NFSv4.1 server <bcp14>MUST</bcp14> use Table B.2 to map case when processing | |||
utf8str_cs strings. Whether the server maps from lower to upper case | utf8str_cs strings. Whether the server maps from lower to upper case | |||
or from upper to lower case is an implementation dependency. | or from upper to lower case is an implementation dependency. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" title="Normalization used by nfs4_cs_prep"> | <section toc="exclude" numbered="true"> | |||
<t> | <name>Normalization used by nfs4_cs_prep</name> | |||
<t> | ||||
The nfs4_cs_prep profile does not specify a normalization form. A | The nfs4_cs_prep profile does not specify a normalization form. A | |||
later revision of this specification may specify a particular | later revision of this specification may specify a particular | |||
normalization form. Therefore, the server and client can expect that | normalization form. Therefore, the server and client can expect that | |||
they may receive unnormalized characters within protocol requests and | they may receive unnormalized characters within protocol requests and | |||
responses. If the operating environment requires normalization, then | responses. If the operating environment requires normalization, then | |||
the implementation must normalize utf8str_cs strings within the | the implementation must normalize utf8str_cs strings within the | |||
protocol before presenting the information to an application (at the | protocol before presenting the information to an application (at the | |||
client) or local file system (at the server). | client) or local file system (at the server). | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" title="Prohibited Output for nfs4_cs_prep"> | <section toc="exclude" numbered="true"> | |||
<t> | <name>Prohibited Output for nfs4_cs_prep</name> | |||
<t> | ||||
The nfs4_cs_prep profile RECOMMENDS prohibiting the use of the | The nfs4_cs_prep profile RECOMMENDS prohibiting the use of the | |||
following tables from stringprep: | following tables from stringprep: | |||
<list style='empty'> | ||||
<t>Table C.5</t> | ||||
<t>Table C.6</t> | ||||
</list> | ||||
</t> | </t> | |||
</section> | <ul empty="true" spacing="normal"> | |||
<section toc="exclude" title="Bidirectional Output for nfs4_cs_prep"> | <li>Table C.5</li> | |||
<t> | <li>Table C.6</li> | |||
</ul> | ||||
</section> | ||||
<section toc="exclude" numbered="true"> | ||||
<name>Bidirectional Output for nfs4_cs_prep</name> | ||||
<t> | ||||
The nfs4_cs_prep profile does not specify any checking of | The nfs4_cs_prep profile does not specify any checking of | |||
bidirectional strings. | bidirectional strings. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section title="Stringprep Profile for the utf8str_cis Type"> | <section numbered="true" toc="default"> | |||
<t> | <name>Stringprep Profile for the utf8str_cis Type</name> | |||
<t> | ||||
Every use of the utf8str_cis type definition in the NFSv4.1 | Every use of the utf8str_cis type definition in the NFSv4.1 | |||
protocol specification follows the profile named nfs4_cis_prep. | protocol specification follows the profile named nfs4_cis_prep. | |||
</t> | </t> | |||
<section toc="exclude" title="Intended Applicability of the nfs4_cis_prep Profil | <section toc="exclude" numbered="true"> | |||
e"> | <name>Intended Applicability of the nfs4_cis_prep Profile</name> | |||
<t> | <t> | |||
The utf8str_cis type is a case-insensitive string of | The utf8str_cis type is a case-insensitive string of | |||
UTF-8 characters. Its primary use in NFSv4.1 is | UTF-8 characters. Its primary use in NFSv4.1 is | |||
for naming NFS servers. | for naming NFS servers. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" title="Character Repertoire of nfs4_cis_prep"> | <section toc="exclude" numbered="true"> | |||
<t> | <name>Character Repertoire of nfs4_cis_prep</name> | |||
<t> | ||||
The nfs4_cis_prep profile uses Unicode 3.2, as defined in stringprep's | The nfs4_cis_prep profile uses Unicode 3.2, as defined in stringprep's | |||
Appendix A.1. However, NFSv4.1 implementations are not limited to 3.2. | Appendix A.1. However, NFSv4.1 implementations are not limited to 3.2. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" title="Mapping Used by nfs4_cis_prep"> | <section toc="exclude" numbered="true"> | |||
<t> | <name>Mapping Used by nfs4_cis_prep</name> | |||
<t> | ||||
The nfs4_cis_prep profile specifies mapping using the following tables from | The nfs4_cis_prep profile specifies mapping using the following tables from | |||
stringprep: | stringprep: | |||
<list style='empty'> | ||||
<t>Table B.1</t> | ||||
<t>Table B.2</t> | ||||
</list> | ||||
</t> | </t> | |||
</section> | <ul empty="true" spacing="normal"> | |||
<section toc="exclude" title="Normalization Used by nfs4_cis_prep"> | <li>Table B.1</li> | |||
<t> | <li>Table B.2</li> | |||
</ul> | ||||
</section> | ||||
<section toc="exclude" numbered="true"> | ||||
<name>Normalization Used by nfs4_cis_prep</name> | ||||
<t> | ||||
The nfs4_cis_prep profile specifies using Unicode normalization form | The nfs4_cis_prep profile specifies using Unicode normalization form | |||
KC, as described in stringprep. | KC, as described in stringprep. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" title="Prohibited Output for nfs4_cis_prep"> | <section toc="exclude" numbered="true"> | |||
<t> | <name>Prohibited Output for nfs4_cis_prep</name> | |||
<t> | ||||
The nfs4_cis_prep profile specifies prohibiting using the following | The nfs4_cis_prep profile specifies prohibiting using the following | |||
tables from stringprep: | tables from stringprep: | |||
<list style='empty'> | ||||
<t>Table C.1.2</t> | ||||
<t>Table C.2.2</t> | ||||
<t>Table C.3</t> | ||||
<t>Table C.4</t> | ||||
<t>Table C.5</t> | ||||
<t>Table C.6</t> | ||||
<t>Table C.7</t> | ||||
<t>Table C.8</t> | ||||
<t>Table C.9</t> | ||||
</list> | ||||
</t> | </t> | |||
</section> | <ul empty="true" spacing="normal"> | |||
<section toc="exclude" title="Bidirectional Output for nfs4_cis_prep"> | <li>Table C.1.2</li> | |||
<t> | <li>Table C.2.2</li> | |||
<li>Table C.3</li> | ||||
<li>Table C.4</li> | ||||
<li>Table C.5</li> | ||||
<li>Table C.6</li> | ||||
<li>Table C.7</li> | ||||
<li>Table C.8</li> | ||||
<li>Table C.9</li> | ||||
</ul> | ||||
</section> | ||||
<section toc="exclude" numbered="true"> | ||||
<name>Bidirectional Output for nfs4_cis_prep</name> | ||||
<t> | ||||
The nfs4_cis_prep profile specifies checking bidirectional strings as | The nfs4_cis_prep profile specifies checking bidirectional strings as | |||
described in stringprep's Section 6. | described in stringprep's Section <xref target="RFC3454" sectionFormat="bare" se ction="6"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section title="Stringprep Profile for the utf8str_mixed Type"> | <section numbered="true" toc="default"> | |||
<t> | <name>Stringprep Profile for the utf8str_mixed Type</name> | |||
<t> | ||||
Every use of the utf8str_mixed type definition in the NFSv4.1 | Every use of the utf8str_mixed type definition in the NFSv4.1 | |||
protocol specification follows the profile named nfs4_mixed_prep. | protocol specification follows the profile named nfs4_mixed_prep. | |||
</t> | </t> | |||
<section toc="exclude" title="Intended Applicability of the nfs4_mixed_prep Prof | <section toc="exclude" numbered="true"> | |||
ile"> | <name>Intended Applicability of the nfs4_mixed_prep Profile</name> | |||
<t> | <t> | |||
The utf8str_mixed type is a string of UTF-8 characters, with a prefix | The utf8str_mixed type is a string of UTF-8 characters, with a prefix | |||
that is case sensitive, a separator equal to '@', and a suffix that is a | that is case sensitive, a separator equal to '@', and a suffix that is a | |||
fully qualified domain name. Its primary use in NFSv4.1 is for | fully qualified domain name. Its primary use in NFSv4.1 is for | |||
naming principals identified in an Access Control Entry. | naming principals identified in an Access Control Entry. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" title="Character Repertoire of nfs4_mixed_prep"> | <section toc="exclude" numbered="true"> | |||
<t> | <name>Character Repertoire of nfs4_mixed_prep</name> | |||
<t> | ||||
The nfs4_mixed_prep profile uses Unicode 3.2, as defined in | The nfs4_mixed_prep profile uses Unicode 3.2, as defined in | |||
stringprep's Appendix A.1. | stringprep's Appendix A.1. | |||
However, NFSv4.1 implementations are not limited to 3.2. | However, NFSv4.1 implementations are not limited to 3.2. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" title="Mapping Used by nfs4_cis_prep"> | <section toc="exclude" numbered="true"> | |||
<t> | <name>Mapping Used by nfs4_cis_prep</name> | |||
<t> | ||||
For the prefix and the separator of a utf8str_mixed | For the prefix and the separator of a utf8str_mixed | |||
string, the nfs4_mixed_prep profile specifies mapping | string, the nfs4_mixed_prep profile specifies mapping | |||
using the following table from stringprep: | using the following table from stringprep: | |||
<list style='empty'> | ||||
<t>Table B.1</t> | ||||
</list> | ||||
</t> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li>Table B.1</li> | ||||
</ul> | ||||
<t> | ||||
For the suffix of a utf8str_mixed string, the nfs4_mixed_prep | For the suffix of a utf8str_mixed string, the nfs4_mixed_prep | |||
profile specifies mapping using the following tables from | profile specifies mapping using the following tables from | |||
stringprep: | stringprep: | |||
<list style='empty'> | ||||
<t>Table B.1</t> | ||||
<t>Table B.2</t> | ||||
</list> | ||||
</t> | </t> | |||
</section> | <ul empty="true" spacing="normal"> | |||
<section toc="exclude" title="Normalization Used by nfs4_mixed_prep"> | <li>Table B.1</li> | |||
<t> | <li>Table B.2</li> | |||
</ul> | ||||
</section> | ||||
<section toc="exclude" numbered="true"> | ||||
<name>Normalization Used by nfs4_mixed_prep</name> | ||||
<t> | ||||
The nfs4_mixed_prep profile specifies using Unicode normalization form | The nfs4_mixed_prep profile specifies using Unicode normalization form | |||
KC, as described in stringprep. | KC, as described in stringprep. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" title="Prohibited Output for nfs4_mixed_prep"> | <section toc="exclude" numbered="true"> | |||
<t> | <name>Prohibited Output for nfs4_mixed_prep</name> | |||
<t> | ||||
The nfs4_mixed_prep profile specifies prohibiting using the | The nfs4_mixed_prep profile specifies prohibiting using the | |||
following tables from stringprep: | following tables from stringprep: | |||
<list style='empty'> | ||||
<t>Table C.1.2</t> | ||||
<t>Table C.2.2</t> | ||||
<t>Table C.3</t> | ||||
<t>Table C.4</t> | ||||
<t>Table C.5</t> | ||||
<t>Table C.6</t> | ||||
<t>Table C.7</t> | ||||
<t>Table C.8</t> | ||||
<t>Table C.9</t> | ||||
</list> | ||||
</t> | </t> | |||
</section> | <ul empty="true" spacing="normal"> | |||
<section toc="exclude" title="Bidirectional Output for nfs4_mixed_prep"> | <li>Table C.1.2</li> | |||
<t> | <li>Table C.2.2</li> | |||
<li>Table C.3</li> | ||||
<li>Table C.4</li> | ||||
<li>Table C.5</li> | ||||
<li>Table C.6</li> | ||||
<li>Table C.7</li> | ||||
<li>Table C.8</li> | ||||
<li>Table C.9</li> | ||||
</ul> | ||||
</section> | ||||
<section toc="exclude" numbered="true"> | ||||
<name>Bidirectional Output for nfs4_mixed_prep</name> | ||||
<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 6. | as described in stringprep's Section <xref target="RFC3454" sectionFormat="bare" section="6"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section title="UTF-8 Capabilities" anchor="utf8_caps"> | <section anchor="utf8_caps" numbered="true" toc="default"> | |||
<figure> | <name>UTF-8 Capabilities</name> | |||
<artwork> | <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; | typedef uint32_t fs_charset_cap4;]]></sourcecode> | |||
</artwork> | <t> | |||
</figure> | ||||
<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"/>) | 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. | |||
The first flag is FSCHARSET_CAP4_CONTAINS_NON_UTF8, which, if set | The first flag is FSCHARSET_CAP4_CONTAINS_NON_UTF8, which, if set | |||
to one, tells the client that the file system contains non-UTF-8 characters, | to one, tells the client that the file system contains non-UTF-8 characters, | |||
and the server will not convert non-UTF characters to UTF-8 if the client | and the server will not convert non-UTF characters to UTF-8 if the client | |||
reads a symbolic link or directory, neither will operations with component | reads a symbolic link or directory, neither will operations with component | |||
names or pathnames in the arguments convert the strings to UTF-8. | names or pathnames in the arguments convert the strings to UTF-8. | |||
The second flag is FSCHARSET_CAP4_ALLOWS_ONLY_UTF8, which, if set to | The second flag is FSCHARSET_CAP4_ALLOWS_ONLY_UTF8, which, if set to | |||
one, indicates that the server will accept (and generate) only | one, indicates that the server will accept (and generate) only | |||
UTF-8 characters on the file system. If | UTF-8 characters on the file system. If | |||
FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 is set to one, | FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 is set to one, | |||
FSCHARSET_CAP4_CONTAINS_NON_UTF8 MUST be set to zero. | FSCHARSET_CAP4_CONTAINS_NON_UTF8 <bcp14>MUST</bcp14> be set to zero. | |||
FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 SHOULD always be set to one. | FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 <bcp14>SHOULD</bcp14> always be set to one. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="UTF-8 Related Errors" anchor="utf8_related_errors"> | <section anchor="utf8_related_errors" numbered="true" toc="default"> | |||
<t> | <name>UTF-8 Related Errors</name> | |||
<t> | ||||
Where the client sends an invalid UTF-8 string, the server should | Where the client sends an invalid UTF-8 string, the server should | |||
return NFS4ERR_INVAL (see <xref target="error_definitions"/>). | return NFS4ERR_INVAL (see <xref target="error_definitions" format="default"/>). | |||
This includes cases in which inappropriate prefixes are detected and | This includes cases in which inappropriate prefixes are detected and | |||
where the count includes trailing bytes that do not constitute a full | where the count includes trailing bytes that do not constitute a full | |||
UCS character. | UCS character. | |||
</t> | </t> | |||
<t> | <t> | |||
Where the client-supplied string is valid UTF-8 but contains | Where the client-supplied string is valid UTF-8 but contains | |||
characters that are not supported by the server as a value for that | characters that are not supported by the server as a value for that | |||
string (e.g., names containing characters outside of Unicode plane 0 on | string (e.g., names containing characters outside of Unicode plane 0 on | |||
file systems that fail to support such characters despite their | file systems that fail to support such characters despite their | |||
presence in the Unicode standard), the server should return | presence in the Unicode standard), the server should return | |||
NFS4ERR_BADCHAR. | NFS4ERR_BADCHAR. | |||
</t> | </t> | |||
<t> | <t> | |||
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 | particular name to be used, the server should return the error <xref target="err | |||
target="error_definitions">NFS4ERR_BADNAME</xref>. This includes | or_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> | |||
<!-- $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 title="Error Values"> | <section numbered="true" toc="default"> | |||
<t> | <name>Error Values</name> | |||
<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 | |||
error status will be entered in the reply and the Compound | error status will be entered in the reply and the Compound | |||
request will be terminated. | request will be terminated. | |||
</t> | </t> | |||
<section title="Error Definitions"> | <section numbered="true" toc="default"> | |||
<texttable anchor='error_definitions'> | <name>Error Definitions</name> | |||
<preamble> | <table anchor="error_definitions" align="center"> | |||
Protocol Error Definitions | <name> Protocol Error Definitions</name> | |||
</preamble> | <thead> | |||
<ttcol align='left'>Error</ttcol> | <tr> | |||
<ttcol align='left'>Number</ttcol> | <th align="left">Error</th> | |||
<ttcol align='left'>Description</ttcol> | <th align="left">Number</th> | |||
<th align="left">Description</th> | ||||
<c>NFS4_OK</c> | </tr> | |||
<c>0</c> | </thead> | |||
<c><xref target="err_OK" /></c> | <tbody> | |||
<tr> | ||||
<c>NFS4ERR_ACCESS</c> | <td align="left">NFS4_OK</td> | |||
<c>13</c> | <td align="left">0</td> | |||
<c><xref target="err_ACCESS" /></c> | <td align="left"> | |||
<xref target="err_OK" format="default"/></td> | ||||
<c>NFS4ERR_ATTRNOTSUPP</c> | </tr> | |||
<c>10032</c> | <tr> | |||
<c><xref target="err_ATTRNOTSUPP" /></c> | <td align="left">NFS4ERR_ACCESS</td> | |||
<td align="left">13</td> | ||||
<c>NFS4ERR_ADMIN_REVOKED</c> | <td align="left"> | |||
<c>10047</c> | <xref target="err_ACCESS" format="default"/></td> | |||
<c><xref target="err_ADMIN_REVOKED" /></c> | </tr> | |||
<tr> | ||||
<c>NFS4ERR_BACK_CHAN_BUSY</c> | <td align="left">NFS4ERR_ATTRNOTSUPP</td> | |||
<c>10057</c> | <td align="left">10032</td> | |||
<c><xref target="err_BACK_CHAN_BUSY" /></c> | <td align="left"> | |||
<xref target="err_ATTRNOTSUPP" format="default"/></td> | ||||
<c>NFS4ERR_BADCHAR</c> | </tr> | |||
<c>10040</c> | <tr> | |||
<c><xref target="err_BADCHAR" /></c> | <td align="left">NFS4ERR_ADMIN_REVOKED</td> | |||
<td align="left">10047</td> | ||||
<c>NFS4ERR_BADHANDLE</c> | <td align="left"> | |||
<c>10001</c> | <xref target="err_ADMIN_REVOKED" format="default"/></td> | |||
<c><xref target="err_BADHANDLE" /></c> | </tr> | |||
<tr> | ||||
<c>NFS4ERR_BADIOMODE</c> | <td align="left">NFS4ERR_BACK_CHAN_BUSY</td> | |||
<c>10049</c> | <td align="left">10057</td> | |||
<c><xref target="err_BADIOMODE" /></c> | <td align="left"> | |||
<xref target="err_BACK_CHAN_BUSY" format="default"/></td> | ||||
<c>NFS4ERR_BADLAYOUT</c> | </tr> | |||
<c>10050</c> | <tr> | |||
<c><xref target="err_BADLAYOUT" /></c> | <td align="left">NFS4ERR_BADCHAR</td> | |||
<td align="left">10040</td> | ||||
<c>NFS4ERR_BADNAME</c> | <td align="left"> | |||
<c>10041</c> | <xref target="err_BADCHAR" format="default"/></td> | |||
<c><xref target="err_BADNAME" /></c> | </tr> | |||
<tr> | ||||
<c>NFS4ERR_BADOWNER</c> | <td align="left">NFS4ERR_BADHANDLE</td> | |||
<c>10039</c> | <td align="left">10001</td> | |||
<c><xref target="err_BADOWNER" /></c> | <td align="left"> | |||
<xref target="err_BADHANDLE" format="default"/></td> | ||||
<c>NFS4ERR_BADSESSION</c> | </tr> | |||
<c>10052</c> | <tr> | |||
<c><xref target="err_BADSESSION" /></c> | <td align="left">NFS4ERR_BADIOMODE</td> | |||
<td align="left">10049</td> | ||||
<c>NFS4ERR_BADSLOT</c> | <td align="left"> | |||
<c>10053</c> | <xref target="err_BADIOMODE" format="default"/></td> | |||
<c><xref target="err_BADSLOT" /></c> | </tr> | |||
<tr> | ||||
<c>NFS4ERR_BADTYPE</c> | <td align="left">NFS4ERR_BADLAYOUT</td> | |||
<c>10007</c> | <td align="left">10050</td> | |||
<c><xref target="err_BADTYPE" /></c> | <td align="left"> | |||
<xref target="err_BADLAYOUT" format="default"/></td> | ||||
<c>NFS4ERR_BADXDR</c> | </tr> | |||
<c>10036</c> | <tr> | |||
<c><xref target="err_BADXDR" /></c> | <td align="left">NFS4ERR_BADNAME</td> | |||
<td align="left">10041</td> | ||||
<c>NFS4ERR_BAD_COOKIE</c> | <td align="left"> | |||
<c>10003</c> | <xref target="err_BADNAME" format="default"/></td> | |||
<c><xref target="err_BAD_COOKIE" /></c> | </tr> | |||
<tr> | ||||
<c>NFS4ERR_BAD_HIGH_SLOT</c> | <td align="left">NFS4ERR_BADOWNER</td> | |||
<c>10077</c> | <td align="left">10039</td> | |||
<c><xref target="err_BAD_HIGH_SLOT" /></c> | <td align="left"> | |||
<xref target="err_BADOWNER" format="default"/></td> | ||||
<c>NFS4ERR_BAD_RANGE</c> | </tr> | |||
<c>10042</c> | <tr> | |||
<c><xref target="err_BAD_RANGE" /></c> | <td align="left">NFS4ERR_BADSESSION</td> | |||
<td align="left">10052</td> | ||||
<c>NFS4ERR_BAD_SEQID</c> | <td align="left"> | |||
<c>10026</c> | <xref target="err_BADSESSION" format="default"/></td> | |||
<c><xref target="err_BAD_SEQID" /></c> | </tr> | |||
<tr> | ||||
<c>NFS4ERR_BAD_SESSION_DIGEST</c> | <td align="left">NFS4ERR_BADSLOT</td> | |||
<c>10051</c> | <td align="left">10053</td> | |||
<c><xref target="err_BAD_SESSION_DIGEST" /></c> | <td align="left"> | |||
<xref target="err_BADSLOT" format="default"/></td> | ||||
<c>NFS4ERR_BAD_STATEID</c> | </tr> | |||
<c>10025</c> | <tr> | |||
<c><xref target="err_BAD_STATEID" /></c> | <td align="left">NFS4ERR_BADTYPE</td> | |||
<td align="left">10007</td> | ||||
<c>NFS4ERR_CB_PATH_DOWN</c> | <td align="left"> | |||
<c>10048</c> | <xref target="err_BADTYPE" format="default"/></td> | |||
<c><xref target="err_CB_PATH_DOWN" /></c> | </tr> | |||
<tr> | ||||
<c>NFS4ERR_CLID_INUSE</c> | <td align="left">NFS4ERR_BADXDR</td> | |||
<c>10017</c> | <td align="left">10036</td> | |||
<c><xref target="err_CLID_INUSE" /></c> | <td align="left"> | |||
<xref target="err_BADXDR" format="default"/></td> | ||||
<c>NFS4ERR_CLIENTID_BUSY</c> | </tr> | |||
<c>10074</c> | <tr> | |||
<c><xref target="err_CLIENTID_BUSY" /></c> | <td align="left">NFS4ERR_BAD_COOKIE</td> | |||
<td align="left">10003</td> | ||||
<c>NFS4ERR_COMPLETE_ALREADY</c> | <td align="left"> | |||
<c>10054</c> | <xref target="err_BAD_COOKIE" format="default"/></td> | |||
<c><xref target="err_COMPLETE_ALREADY" /></c> | </tr> | |||
<tr> | ||||
<c>NFS4ERR_CONN_NOT_BOUND_TO_SESSION</c> | <td align="left">NFS4ERR_BAD_HIGH_SLOT</td> | |||
<c>10055</c> | <td align="left">10077</td> | |||
<c><xref target="err_CONN_NOT_BOUND_TO_SESSION" /></c> | <td align="left"> | |||
<xref target="err_BAD_HIGH_SLOT" format="default"/></td> | ||||
<c>NFS4ERR_DEADLOCK</c> | </tr> | |||
<c>10045</c> | <tr> | |||
<c><xref target="err_DEADLOCK" /></c> | <td align="left">NFS4ERR_BAD_RANGE</td> | |||
<td align="left">10042</td> | ||||
<c>NFS4ERR_DEADSESSION</c> | <td align="left"> | |||
<c>10078</c> | <xref target="err_BAD_RANGE" format="default"/></td> | |||
<c><xref target="err_DEADSESSION" /></c> | </tr> | |||
<tr> | ||||
<c>NFS4ERR_DELAY</c> | <td align="left">NFS4ERR_BAD_SEQID</td> | |||
<c>10008</c> | <td align="left">10026</td> | |||
<c><xref target="err_DELAY" /></c> | <td align="left"> | |||
<xref target="err_BAD_SEQID" format="default"/></td> | ||||
<c>NFS4ERR_DELEG_ALREADY_WANTED</c> | </tr> | |||
<c>10056</c> | <tr> | |||
<c><xref target="err_DELEG_ALREADY_WANTED" /></c> | <td align="left">NFS4ERR_BAD_SESSION_DIGEST</td> | |||
<td align="left">10051</td> | ||||
<c>NFS4ERR_DELEG_REVOKED</c> | <td align="left"> | |||
<c>10087</c> | <xref target="err_BAD_SESSION_DIGEST" format="default"/></td> | |||
<c><xref target="err_DELEG_REVOKED" /></c> | </tr> | |||
<tr> | ||||
<c>NFS4ERR_DENIED</c> | <td align="left">NFS4ERR_BAD_STATEID</td> | |||
<c>10010</c> | <td align="left">10025</td> | |||
<c><xref target="err_DENIED" /></c> | <td align="left"> | |||
<xref target="err_BAD_STATEID" format="default"/></td> | ||||
<c>NFS4ERR_DIRDELEG_UNAVAIL</c> | </tr> | |||
<c>10084</c> | <tr> | |||
<c><xref target="err_DIRDELEG_UNAVAIL" /></c> | <td align="left">NFS4ERR_CB_PATH_DOWN</td> | |||
<td align="left">10048</td> | ||||
<c>NFS4ERR_DQUOT</c> | <td align="left"> | |||
<c>69</c> | <xref target="err_CB_PATH_DOWN" format="default"/></td> | |||
<c><xref target="err_DQUOT" /></c> | </tr> | |||
<tr> | ||||
<c>NFS4ERR_ENCR_ALG_UNSUPP</c> | <td align="left">NFS4ERR_CLID_INUSE</td> | |||
<c>10079</c> | <td align="left">10017</td> | |||
<c><xref target="err_ENCR_ALG_UNSUPP" /></c> | <td align="left"> | |||
<xref target="err_CLID_INUSE" format="default"/></td> | ||||
<c>NFS4ERR_EXIST</c> | </tr> | |||
<c>17</c> | <tr> | |||
<c><xref target="err_EXIST" /></c> | <td align="left">NFS4ERR_CLIENTID_BUSY</td> | |||
<td align="left">10074</td> | ||||
<c>NFS4ERR_EXPIRED</c> | <td align="left"> | |||
<c>10011</c> | <xref target="err_CLIENTID_BUSY" format="default"/></td> | |||
<c><xref target="err_EXPIRED" /></c> | </tr> | |||
<tr> | ||||
<c>NFS4ERR_FBIG</c> | <td align="left">NFS4ERR_COMPLETE_ALREADY</td> | |||
<c>27</c> | <td align="left">10054</td> | |||
<c><xref target="err_FBIG" /></c> | <td align="left"> | |||
<xref target="err_COMPLETE_ALREADY" format="default"/></td> | ||||
<c>NFS4ERR_FHEXPIRED</c> | </tr> | |||
<c>10014</c> | <tr> | |||
<c><xref target="err_FHEXPIRED" /></c> | <td align="left">NFS4ERR_CONN_NOT_BOUND_TO_SESSION</td> | |||
<td align="left">10055</td> | ||||
<c>NFS4ERR_FILE_OPEN</c> | <td align="left"> | |||
<c>10046</c> | <xref target="err_CONN_NOT_BOUND_TO_SESSION" format="default"/>< | |||
<c><xref target="err_FILE_OPEN" /></c> | /td> | |||
</tr> | ||||
<c>NFS4ERR_GRACE</c> | <tr> | |||
<c>10013</c> | <td align="left">NFS4ERR_DEADLOCK</td> | |||
<c><xref target="err_GRACE" /></c> | <td align="left">10045</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_HASH_ALG_UNSUPP</c> | <xref target="err_DEADLOCK" format="default"/></td> | |||
<c>10072</c> | </tr> | |||
<c><xref target="err_HASH_ALG_UNSUPP" /></c> | <tr> | |||
<td align="left">NFS4ERR_DEADSESSION</td> | ||||
<c>NFS4ERR_INVAL</c> | <td align="left">10078</td> | |||
<c>22</c> | <td align="left"> | |||
<c><xref target="err_INVAL" /></c> | <xref target="err_DEADSESSION" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_IO</c> | <tr> | |||
<c>5</c> | <td align="left">NFS4ERR_DELAY</td> | |||
<c><xref target="err_IO" /></c> | <td align="left">10008</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_ISDIR</c> | <xref target="err_DELAY" format="default"/></td> | |||
<c>21</c> | </tr> | |||
<c><xref target="err_ISDIR" /></c> | <tr> | |||
<td align="left">NFS4ERR_DELEG_ALREADY_WANTED</td> | ||||
<c>NFS4ERR_LAYOUTTRYLATER</c> | <td align="left">10056</td> | |||
<c>10058</c> | <td align="left"> | |||
<c><xref target="err_LAYOUTTRYLATER" /></c> | <xref target="err_DELEG_ALREADY_WANTED" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_LAYOUTUNAVAILABLE</c> | <tr> | |||
<c>10059</c> | <td align="left">NFS4ERR_DELEG_REVOKED</td> | |||
<c><xref target="err_LAYOUTUNAVAILABLE" /></c> | <td align="left">10087</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_LEASE_MOVED</c> | <xref target="err_DELEG_REVOKED" format="default"/></td> | |||
<c>10031</c> | </tr> | |||
<c><xref target="err_LEASE_MOVED" /></c> | <tr> | |||
<td align="left">NFS4ERR_DENIED</td> | ||||
<c>NFS4ERR_LOCKED</c> | <td align="left">10010</td> | |||
<c>10012</c> | <td align="left"> | |||
<c><xref target="err_LOCKED" /></c> | <xref target="err_DENIED" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_LOCKS_HELD</c> | <tr> | |||
<c>10037</c> | <td align="left">NFS4ERR_DIRDELEG_UNAVAIL</td> | |||
<c><xref target="err_LOCKS_HELD" /></c> | <td align="left">10084</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_LOCK_NOTSUPP</c> | <xref target="err_DIRDELEG_UNAVAIL" format="default"/></td> | |||
<c>10043</c> | </tr> | |||
<c><xref target="err_LOCK_NOTSUPP" /></c> | <tr> | |||
<td align="left">NFS4ERR_DQUOT</td> | ||||
<c>NFS4ERR_LOCK_RANGE</c> | <td align="left">69</td> | |||
<c>10028</c> | <td align="left"> | |||
<c><xref target="err_LOCK_RANGE" /></c> | <xref target="err_DQUOT" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_MINOR_VERS_MISMATCH</c> | <tr> | |||
<c>10021</c> | <td align="left">NFS4ERR_ENCR_ALG_UNSUPP</td> | |||
<c><xref target="err_MINOR_VERS_MISMATCH" /></c> | <td align="left">10079</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_MLINK</c> | <xref target="err_ENCR_ALG_UNSUPP" format="default"/></td> | |||
<c>31</c> | </tr> | |||
<c><xref target="err_MLINK" /></c> | <tr> | |||
<td align="left">NFS4ERR_EXIST</td> | ||||
<c>NFS4ERR_MOVED</c> | <td align="left">17</td> | |||
<c>10019</c> | <td align="left"> | |||
<c><xref target="err_MOVED" /></c> | <xref target="err_EXIST" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_NAMETOOLONG</c> | <tr> | |||
<c>63</c> | <td align="left">NFS4ERR_EXPIRED</td> | |||
<c><xref target="err_NAMETOOLONG" /></c> | <td align="left">10011</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_NOENT</c> | <xref target="err_EXPIRED" format="default"/></td> | |||
<c>2</c> | </tr> | |||
<c><xref target="err_NOENT" /></c> | <tr> | |||
<td align="left">NFS4ERR_FBIG</td> | ||||
<c>NFS4ERR_NOFILEHANDLE</c> | <td align="left">27</td> | |||
<c>10020</c> | <td align="left"> | |||
<c><xref target="err_NOFILEHANDLE" /></c> | <xref target="err_FBIG" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_NOMATCHING_LAYOUT</c> | <tr> | |||
<c>10060</c> | <td align="left">NFS4ERR_FHEXPIRED</td> | |||
<c><xref target="err_NOMATCHING_LAYOUT" /></c> | <td align="left">10014</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_NOSPC</c> | <xref target="err_FHEXPIRED" format="default"/></td> | |||
<c>28</c> | </tr> | |||
<c><xref target="err_NOSPC" /></c> | <tr> | |||
<td align="left">NFS4ERR_FILE_OPEN</td> | ||||
<c>NFS4ERR_NOTDIR</c> | <td align="left">10046</td> | |||
<c>20</c> | <td align="left"> | |||
<c><xref target="err_NOTDIR" /></c> | <xref target="err_FILE_OPEN" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_NOTEMPTY</c> | <tr> | |||
<c>66</c> | <td align="left">NFS4ERR_GRACE</td> | |||
<c><xref target="err_NOTEMPTY" /></c> | <td align="left">10013</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_NOTSUPP</c> | <xref target="err_GRACE" format="default"/></td> | |||
<c>10004</c> | </tr> | |||
<c><xref target="err_NOTSUPP" /></c> | <tr> | |||
<td align="left">NFS4ERR_HASH_ALG_UNSUPP</td> | ||||
<c>NFS4ERR_NOT_ONLY_OP</c> | <td align="left">10072</td> | |||
<c>10081</c> | <td align="left"> | |||
<c><xref target="err_NOT_ONLY_OP" /></c> | <xref target="err_HASH_ALG_UNSUPP" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_NOT_SAME</c> | <tr> | |||
<c>10027</c> | <td align="left">NFS4ERR_INVAL</td> | |||
<c><xref target="err_NOT_SAME" /></c> | <td align="left">22</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_NO_GRACE</c> | <xref target="err_INVAL" format="default"/></td> | |||
<c>10033</c> | </tr> | |||
<c><xref target="err_NO_GRACE" /></c> | <tr> | |||
<td align="left">NFS4ERR_IO</td> | ||||
<c>NFS4ERR_NXIO</c> | <td align="left">5</td> | |||
<c>6</c> | <td align="left"> | |||
<c><xref target="err_NXIO" /></c> | <xref target="err_IO" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_OLD_STATEID</c> | <tr> | |||
<c>10024</c> | <td align="left">NFS4ERR_ISDIR</td> | |||
<c><xref target="err_OLD_STATEID" /></c> | <td align="left">21</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_OPENMODE</c> | <xref target="err_ISDIR" format="default"/></td> | |||
<c>10038</c> | </tr> | |||
<c><xref target="err_OPENMODE" /></c> | <tr> | |||
<td align="left">NFS4ERR_LAYOUTTRYLATER</td> | ||||
<c>NFS4ERR_OP_ILLEGAL</c> | <td align="left">10058</td> | |||
<c>10044</c> | <td align="left"> | |||
<c><xref target="err_OP_ILLEGAL" /></c> | <xref target="err_LAYOUTTRYLATER" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_OP_NOT_IN_SESSION</c> | <tr> | |||
<c>10071</c> | <td align="left">NFS4ERR_LAYOUTUNAVAILABLE</td> | |||
<c><xref target="err_OP_NOT_IN_SESSION" /></c> | <td align="left">10059</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_PERM</c> | <xref target="err_LAYOUTUNAVAILABLE" format="default"/></td> | |||
<c>1</c> | </tr> | |||
<c><xref target="err_PERM" /></c> | <tr> | |||
<td align="left">NFS4ERR_LEASE_MOVED</td> | ||||
<c>NFS4ERR_PNFS_IO_HOLE</c> | <td align="left">10031</td> | |||
<c>10075</c> | <td align="left"> | |||
<c><xref target="err_PNFS_IO_HOLE" /></c> | <xref target="err_LEASE_MOVED" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_PNFS_NO_LAYOUT</c> | <tr> | |||
<c>10080</c> | <td align="left">NFS4ERR_LOCKED</td> | |||
<c><xref target="err_PNFS_NO_LAYOUT" /></c> | <td align="left">10012</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_RECALLCONFLICT</c> | <xref target="err_LOCKED" format="default"/></td> | |||
<c>10061</c> | </tr> | |||
<c><xref target="err_RECALLCONFLICT" /></c> | <tr> | |||
<td align="left">NFS4ERR_LOCKS_HELD</td> | ||||
<c>NFS4ERR_RECLAIM_BAD</c> | <td align="left">10037</td> | |||
<c>10034</c> | <td align="left"> | |||
<c><xref target="err_RECLAIM_BAD" /></c> | <xref target="err_LOCKS_HELD" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_RECLAIM_CONFLICT</c> | <tr> | |||
<c>10035</c> | <td align="left">NFS4ERR_LOCK_NOTSUPP</td> | |||
<c><xref target="err_RECLAIM_CONFLICT" /></c> | <td align="left">10043</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_REJECT_DELEG</c> | <xref target="err_LOCK_NOTSUPP" format="default"/></td> | |||
<c>10085</c> | </tr> | |||
<c><xref target="err_REJECT_DELEG" /></c> | <tr> | |||
<td align="left">NFS4ERR_LOCK_RANGE</td> | ||||
<c>NFS4ERR_REP_TOO_BIG</c> | <td align="left">10028</td> | |||
<c>10066</c> | <td align="left"> | |||
<c><xref target="err_REP_TOO_BIG" /></c> | <xref target="err_LOCK_RANGE" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_REP_TOO_BIG_TO_CACHE</c> | <tr> | |||
<c>10067</c> | <td align="left">NFS4ERR_MINOR_VERS_MISMATCH</td> | |||
<c><xref target="err_REP_TOO_BIG_TO_CACHE" /></c> | <td align="left">10021</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_REQ_TOO_BIG</c> | <xref target="err_MINOR_VERS_MISMATCH" format="default"/></td> | |||
<c>10065</c> | </tr> | |||
<c><xref target="err_REQ_TOO_BIG" /></c> | <tr> | |||
<td align="left">NFS4ERR_MLINK</td> | ||||
<c>NFS4ERR_RESTOREFH</c> | <td align="left">31</td> | |||
<c>10030</c> | <td align="left"> | |||
<c><xref target="err_RESTOREFH" /></c> | <xref target="err_MLINK" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_RETRY_UNCACHED_REP</c> | <tr> | |||
<c>10068</c> | <td align="left">NFS4ERR_MOVED</td> | |||
<c><xref target="err_RETRY_UNCACHED_REP" /></c> | <td align="left">10019</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_RETURNCONFLICT</c> | <xref target="err_MOVED" format="default"/></td> | |||
<c>10086</c> | </tr> | |||
<c><xref target="err_RETURNCONFLICT" /></c> | <tr> | |||
<td align="left">NFS4ERR_NAMETOOLONG</td> | ||||
<c>NFS4ERR_ROFS</c> | <td align="left">63</td> | |||
<c>30</c> | <td align="left"> | |||
<c><xref target="err_ROFS" /></c> | <xref target="err_NAMETOOLONG" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_SAME</c> | <tr> | |||
<c>10009</c> | <td align="left">NFS4ERR_NOENT</td> | |||
<c><xref target="err_SAME" /></c> | <td align="left">2</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_SHARE_DENIED</c> | <xref target="err_NOENT" format="default"/></td> | |||
<c>10015</c> | </tr> | |||
<c><xref target="err_SHARE_DENIED" /></c> | <tr> | |||
<td align="left">NFS4ERR_NOFILEHANDLE</td> | ||||
<c>NFS4ERR_SEQUENCE_POS</c> | <td align="left">10020</td> | |||
<c>10064</c> | <td align="left"> | |||
<c><xref target="err_SEQUENCE_POS" /></c> | <xref target="err_NOFILEHANDLE" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_SEQ_FALSE_RETRY</c> | <tr> | |||
<c>10076</c> | <td align="left">NFS4ERR_NOMATCHING_LAYOUT</td> | |||
<c><xref target="err_SEQ_FALSE_RETRY" /></c> | <td align="left">10060</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_SEQ_MISORDERED</c> | <xref target="err_NOMATCHING_LAYOUT" format="default"/></td> | |||
<c>10063</c> | </tr> | |||
<c><xref target="err_SEQ_MISORDERED" /></c> | <tr> | |||
<td align="left">NFS4ERR_NOSPC</td> | ||||
<c>NFS4ERR_SERVERFAULT</c> | <td align="left">28</td> | |||
<c>10006</c> | <td align="left"> | |||
<c><xref target="err_SERVERFAULT" /></c> | <xref target="err_NOSPC" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_STALE</c> | <tr> | |||
<c>70</c> | <td align="left">NFS4ERR_NOTDIR</td> | |||
<c><xref target="err_STALE" /></c> | <td align="left">20</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_STALE_CLIENTID</c> | <xref target="err_NOTDIR" format="default"/></td> | |||
<c>10022</c> | </tr> | |||
<c><xref target="err_STALE_CLIENTID" /></c> | <tr> | |||
<td align="left">NFS4ERR_NOTEMPTY</td> | ||||
<c>NFS4ERR_STALE_STATEID</c> | <td align="left">66</td> | |||
<c>10023</c> | <td align="left"> | |||
<c><xref target="err_STALE_STATEID" /></c> | <xref target="err_NOTEMPTY" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_SYMLINK</c> | <tr> | |||
<c>10029</c> | <td align="left">NFS4ERR_NOTSUPP</td> | |||
<c><xref target="err_SYMLINK" /></c> | <td align="left">10004</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_TOOSMALL</c> | <xref target="err_NOTSUPP" format="default"/></td> | |||
<c>10005</c> | </tr> | |||
<c><xref target="err_TOOSMALL" /></c> | <tr> | |||
<td align="left">NFS4ERR_NOT_ONLY_OP</td> | ||||
<c>NFS4ERR_TOO_MANY_OPS</c> | <td align="left">10081</td> | |||
<c>10070</c> | <td align="left"> | |||
<c><xref target="err_TOO_MANY_OPS" /></c> | <xref target="err_NOT_ONLY_OP" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_UNKNOWN_LAYOUTTYPE</c> | <tr> | |||
<c>10062</c> | <td align="left">NFS4ERR_NOT_SAME</td> | |||
<c><xref target="err_UNKNOWN_LAYOUTTYPE" /></c> | <td align="left">10027</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_UNSAFE_COMPOUND</c> | <xref target="err_NOT_SAME" format="default"/></td> | |||
<c>10069</c> | </tr> | |||
<c><xref target="err_UNSAFE_COMPOUND" /></c> | <tr> | |||
<td align="left">NFS4ERR_NO_GRACE</td> | ||||
<c>NFS4ERR_WRONGSEC</c> | <td align="left">10033</td> | |||
<c>10016</c> | <td align="left"> | |||
<c><xref target="err_WRONGSEC" /></c> | <xref target="err_NO_GRACE" format="default"/></td> | |||
</tr> | ||||
<c>NFS4ERR_WRONG_CRED</c> | <tr> | |||
<c>10082</c> | <td align="left">NFS4ERR_NXIO</td> | |||
<c><xref target="err_WRONG_CRED" /></c> | <td align="left">6</td> | |||
<td align="left"> | ||||
<c>NFS4ERR_WRONG_TYPE</c> | <xref target="err_NXIO" format="default"/></td> | |||
<c>10083</c> | </tr> | |||
<c><xref target="err_WRONG_TYPE" /></c> | <tr> | |||
<td align="left">NFS4ERR_OLD_STATEID</td> | ||||
<c>NFS4ERR_XDEV</c> | <td align="left">10024</td> | |||
<c>18</c> | <td align="left"> | |||
<c><xref target="err_XDEV" /></c> | <xref target="err_OLD_STATEID" format="default"/></td> | |||
</tr> | ||||
</texttable> | <tr> | |||
<section title="General Errors" anchor="errors_gen"> | <td align="left">NFS4ERR_OPENMODE</td> | |||
<t> | <td align="left">10038</td> | |||
<td align="left"> | ||||
<xref target="err_OPENMODE" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_OP_ILLEGAL</td> | ||||
<td align="left">10044</td> | ||||
<td align="left"> | ||||
<xref target="err_OP_ILLEGAL" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_OP_NOT_IN_SESSION</td> | ||||
<td align="left">10071</td> | ||||
<td align="left"> | ||||
<xref target="err_OP_NOT_IN_SESSION" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_PERM</td> | ||||
<td align="left">1</td> | ||||
<td align="left"> | ||||
<xref target="err_PERM" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_PNFS_IO_HOLE</td> | ||||
<td align="left">10075</td> | ||||
<td align="left"> | ||||
<xref target="err_PNFS_IO_HOLE" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_PNFS_NO_LAYOUT</td> | ||||
<td align="left">10080</td> | ||||
<td align="left"> | ||||
<xref target="err_PNFS_NO_LAYOUT" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_RECALLCONFLICT</td> | ||||
<td align="left">10061</td> | ||||
<td align="left"> | ||||
<xref target="err_RECALLCONFLICT" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_RECLAIM_BAD</td> | ||||
<td align="left">10034</td> | ||||
<td align="left"> | ||||
<xref target="err_RECLAIM_BAD" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_RECLAIM_CONFLICT</td> | ||||
<td align="left">10035</td> | ||||
<td align="left"> | ||||
<xref target="err_RECLAIM_CONFLICT" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_REJECT_DELEG</td> | ||||
<td align="left">10085</td> | ||||
<td align="left"> | ||||
<xref target="err_REJECT_DELEG" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_REP_TOO_BIG</td> | ||||
<td align="left">10066</td> | ||||
<td align="left"> | ||||
<xref target="err_REP_TOO_BIG" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_REP_TOO_BIG_TO_CACHE</td> | ||||
<td align="left">10067</td> | ||||
<td align="left"> | ||||
<xref target="err_REP_TOO_BIG_TO_CACHE" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_REQ_TOO_BIG</td> | ||||
<td align="left">10065</td> | ||||
<td align="left"> | ||||
<xref target="err_REQ_TOO_BIG" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_RESTOREFH</td> | ||||
<td align="left">10030</td> | ||||
<td align="left"> | ||||
<xref target="err_RESTOREFH" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_RETRY_UNCACHED_REP</td> | ||||
<td align="left">10068</td> | ||||
<td align="left"> | ||||
<xref target="err_RETRY_UNCACHED_REP" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_RETURNCONFLICT</td> | ||||
<td align="left">10086</td> | ||||
<td align="left"> | ||||
<xref target="err_RETURNCONFLICT" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_ROFS</td> | ||||
<td align="left">30</td> | ||||
<td align="left"> | ||||
<xref target="err_ROFS" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_SAME</td> | ||||
<td align="left">10009</td> | ||||
<td align="left"> | ||||
<xref target="err_SAME" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_SHARE_DENIED</td> | ||||
<td align="left">10015</td> | ||||
<td align="left"> | ||||
<xref target="err_SHARE_DENIED" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_SEQUENCE_POS</td> | ||||
<td align="left">10064</td> | ||||
<td align="left"> | ||||
<xref target="err_SEQUENCE_POS" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_SEQ_FALSE_RETRY</td> | ||||
<td align="left">10076</td> | ||||
<td align="left"> | ||||
<xref target="err_SEQ_FALSE_RETRY" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_SEQ_MISORDERED</td> | ||||
<td align="left">10063</td> | ||||
<td align="left"> | ||||
<xref target="err_SEQ_MISORDERED" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_SERVERFAULT</td> | ||||
<td align="left">10006</td> | ||||
<td align="left"> | ||||
<xref target="err_SERVERFAULT" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_STALE</td> | ||||
<td align="left">70</td> | ||||
<td align="left"> | ||||
<xref target="err_STALE" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_STALE_CLIENTID</td> | ||||
<td align="left">10022</td> | ||||
<td align="left"> | ||||
<xref target="err_STALE_CLIENTID" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_STALE_STATEID</td> | ||||
<td align="left">10023</td> | ||||
<td align="left"> | ||||
<xref target="err_STALE_STATEID" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_SYMLINK</td> | ||||
<td align="left">10029</td> | ||||
<td align="left"> | ||||
<xref target="err_SYMLINK" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_TOOSMALL</td> | ||||
<td align="left">10005</td> | ||||
<td align="left"> | ||||
<xref target="err_TOOSMALL" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_TOO_MANY_OPS</td> | ||||
<td align="left">10070</td> | ||||
<td align="left"> | ||||
<xref target="err_TOO_MANY_OPS" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_UNKNOWN_LAYOUTTYPE</td> | ||||
<td align="left">10062</td> | ||||
<td align="left"> | ||||
<xref target="err_UNKNOWN_LAYOUTTYPE" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_UNSAFE_COMPOUND</td> | ||||
<td align="left">10069</td> | ||||
<td align="left"> | ||||
<xref target="err_UNSAFE_COMPOUND" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_WRONGSEC</td> | ||||
<td align="left">10016</td> | ||||
<td align="left"> | ||||
<xref target="err_WRONGSEC" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_WRONG_CRED</td> | ||||
<td align="left">10082</td> | ||||
<td align="left"> | ||||
<xref target="err_WRONG_CRED" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_WRONG_TYPE</td> | ||||
<td align="left">10083</td> | ||||
<td align="left"> | ||||
<xref target="err_WRONG_TYPE" format="default"/></td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_XDEV</td> | ||||
<td align="left">18</td> | ||||
<td align="left"> | ||||
<xref target="err_XDEV" format="default"/></td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
<section anchor="errors_gen" numbered="true" toc="default"> | ||||
<name>General Errors</name> | ||||
<t> | ||||
This section deals with errors that are applicable to a broad | This section deals with errors that are applicable to a broad | |||
set of different purposes. | set of different purposes. | |||
</t> | </t> | |||
<section title="NFS4ERR_BADXDR (Error Code 10036)" | <section anchor="err_BADXDR" numbered="true" toc="default"> | |||
anchor="err_BADXDR"> | <name>NFS4ERR_BADXDR (Error Code 10036)</name> | |||
<t> | <t> | |||
The arguments for this operation do not match those specified in | The arguments for this operation do not match those specified in | |||
the XDR definition. This includes situations in which the | the XDR definition. This includes situations in which the | |||
request ends before all the arguments have been seen. Note | request ends before all the arguments have been seen. Note | |||
that this error applies when fixed enumerations (these include | that this error applies when fixed enumerations (these include | |||
booleans) have a value within the input stream that is not | booleans) have a value within the input stream that is not | |||
valid for the enum. A replier may pre-parse all operations for | valid for the enum. A replier may pre-parse all operations for | |||
a Compound procedure before doing any operation execution | a Compound procedure before doing any operation execution | |||
and return RPC-level XDR errors in that case. | and return RPC-level XDR errors in that case. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_BAD_COOKIE (Error Code 10003)" | <section anchor="err_BAD_COOKIE" numbered="true" toc="default"> | |||
anchor="err_BAD_COOKIE"> | <name>NFS4ERR_BAD_COOKIE (Error Code 10003)</name> | |||
<t> | <t> | |||
Used for operations that provide a set of information indexed by | Used for operations that provide a set of information indexed by | |||
some quantity provided by the client or cookie sent by the | some quantity provided by the client or cookie sent by the | |||
server for an earlier invocation. Where the value cannot | server for an earlier invocation. Where the value cannot | |||
be used for its intended purpose, this error results. | be used for its intended purpose, this error results. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_DELAY (Error Code 10008)" | <section anchor="err_DELAY" numbered="true" toc="default"> | |||
anchor="err_DELAY"> | <name>NFS4ERR_DELAY (Error Code 10008)</name> | |||
<t> | <t> | |||
For any of a number of reasons, the replier could not | For any of a number of reasons, the replier could not | |||
process this operation in what was deemed a reasonable | process this operation in what was deemed a reasonable | |||
time. The client should wait and then try the request | time. The client should wait and then try the request | |||
with a new slot and sequence value. | with a new slot and sequence value. | |||
</t> | </t> | |||
<t> | ||||
Some examples of scenarios that might lead to this situation: | ||||
<list style="symbols"> | ||||
<t> | <t> | |||
Some examples of scenarios that might lead to this situation: | ||||
</t> | ||||
<ul spacing="normal"> | ||||
<li> | ||||
A server that supports hierarchical storage receives a | A server that supports hierarchical storage receives a | |||
request to process a file that had been migrated. | request to process a file that had been migrated. | |||
</t> | </li> | |||
<t> | <li> | |||
An operation requires a delegation recall to proceed, | An operation requires a delegation recall to proceed, | |||
so that the need to wait for this delegation to be recalled | but the need to wait for this delegation to be recalled | |||
and returned makes processing | and returned makes processing this request in a timely fashion impo | |||
this request in a timely fashion impossible. | ssible. | |||
</t> | </li> | |||
<t> | <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 | from another server as described in <xref target="SEC11-XS-session" | |||
in <xref target="SEC11-XS-session"/>, and the lack | format="default"/>, | |||
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. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <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: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<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 MUST 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. | |||
</t> | </li> | |||
<t> | <li> | |||
If NFS4ERR_DELAY is returned on an operation other than SEQUENCE | If NFS4ERR_DELAY is returned on an operation other than SEQUENCE | |||
which validly appears as the first operation of a request, 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 MUST 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. | |||
</t> | </li> | |||
<t> | <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 MUST contain a SEQUENCE | in the request, the request when retried <bcp14>MUST</bcp14> contain a | |||
operation which is different | SEQUENCE | |||
than the original one, with either the bin id or the sequence value | operation that is different than the original one, with either | |||
different from that in the original request. | the slot ID or the sequence value different from that in the original | |||
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, | NFS4ERR_DELAY error obtained from the reply cache. When no non-idempot | |||
obtained from the replay cache. When no non-idempotent | ent | |||
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. | |||
</t> | </li> | |||
<t> | <li> | |||
<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 | processed before the NFS4ERR_DELAY was returned, reissuing the request | |||
NFS4ERR_DELAY was returned, reissuing the request as is normally | as is normally | |||
done would incorrectly cause the re-execution of the non-idempotent | done would incorrectly cause the re-execution of the non-idempotent ope | |||
operation. | ration. | |||
<vspace blankLines="1"/> | </t> | |||
To avoid this situation, the client should reissue the request | <t> | |||
without the | To avoid this situation, the client should reissue the request without | |||
the | ||||
non-idempotent operation. The request still must use a SEQUENCE | non-idempotent operation. The request still must use a SEQUENCE | |||
operation with either a different slot id or sequence value from | operation with either a different slot ID or sequence value from | |||
the SEQUENCE in the original request. Because this is done, there | the SEQUENCE in the original request. Because this is done, there | |||
is no way the replier could avoid spuriously re-executing the | is no way the replier could avoid spuriously re-executing the | |||
non-idempotent operation since the different SEQUENCE parameters | non-idempotent operation since the different SEQUENCE parameters | |||
prevent the requester from recognizing that the non-idempotent | prevent the requester from recognizing that the non-idempotent | |||
operation is being retried. | operation is being retried. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ul> | |||
<t> | ||||
<t> | ||||
Note that without the ability to return NFS4ERR_DELAY and the | Note that without the ability to return NFS4ERR_DELAY and the | |||
requester's willingness to re-send when receiving it, deadlock might | requester's willingness to re-send when receiving it, deadlock might | |||
result. For example, if a recall is done, and if the delegation | result. For example, if a recall is done, and if the delegation | |||
return or | return or operations preparatory to delegation return are held up by | |||
operations preparatory to delegation return are held up by | ||||
other operations that need the delegation to be returned, | other operations that need the delegation to be returned, | |||
session slots might not be available. The result could be | session slots might not be available. The result could be | |||
deadlock. | deadlock. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_INVAL (Error Code 22)" | <section anchor="err_INVAL" numbered="true" toc="default"> | |||
anchor="err_INVAL"> | <name>NFS4ERR_INVAL (Error Code 22)</name> | |||
<t> | <t> | |||
The arguments for this operation are not valid for some reason, even | The arguments for this operation are not valid for some reason, even | |||
though they do match those specified in the XDR definition for | though they do match those specified in the XDR definition for | |||
the request. | the request. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_NOTSUPP (Error Code 10004)" | <section anchor="err_NOTSUPP" numbered="true" toc="default"> | |||
anchor="err_NOTSUPP"> | <name>NFS4ERR_NOTSUPP (Error Code 10004)</name> | |||
<t> | <t> | |||
Operation not supported, either because the operation is | Operation not supported, either because the operation is | |||
an OPTIONAL one and is not supported by this server or | an <bcp14>OPTIONAL</bcp14> one and is not supported by this server or | |||
because the operation MUST NOT be implemented in | because the operation <bcp14>MUST NOT</bcp14> be implemented in | |||
the current minor version. | the current minor version. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_SERVERFAULT (Error Code 10006)" | <section anchor="err_SERVERFAULT" numbered="true" toc="default"> | |||
anchor="err_SERVERFAULT"> | <name>NFS4ERR_SERVERFAULT (Error Code 10006)</name> | |||
<t> | <t> | |||
An error occurred on the server that does not map to any of | An error occurred on the server that does not map to any of | |||
the specific legal NFSv4.1 protocol error values. The client | the specific legal NFSv4.1 protocol error values. The client | |||
should translate this into an appropriate error. UNIX clients | should translate this into an appropriate error. UNIX clients | |||
may choose to translate this to EIO. | may choose to translate this to EIO. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_TOOSMALL (Error Code 10005)" | <section anchor="err_TOOSMALL" numbered="true" toc="default"> | |||
anchor="err_TOOSMALL"> | <name>NFS4ERR_TOOSMALL (Error Code 10005)</name> | |||
<t> | <t> | |||
Used where an operation returns a variable amount of data, | Used where an operation returns a variable amount of data, | |||
with a limit specified by the client. Where the data | with a limit specified by the client. Where the data | |||
returned cannot be fit within the limit specified by the | returned cannot be fit within the limit specified by the | |||
client, this error results. | client, this error results. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="errors_fh" numbered="true" toc="default"> | ||||
<section title="Filehandle Errors" anchor="errors_fh"> | <name>Filehandle Errors</name> | |||
<t> | <t> | |||
These errors deal with the situation in which the current | These errors deal with the situation in which the current | |||
or saved filehandle, or the filehandle passed to PUTFH | or saved filehandle, or the filehandle passed to PUTFH | |||
intended to become the current filehandle, is invalid | intended to become the current filehandle, is invalid | |||
in some way. This includes situations in which the | in some way. This includes situations in which the | |||
filehandle is a valid filehandle in general but is not | filehandle is a valid filehandle in general but is not | |||
of the appropriate object type for the current operation. | of the appropriate object type for the current operation. | |||
</t> | </t> | |||
<t> | <t> | |||
Where the error description indicates a problem with the | Where the error description indicates a problem with the | |||
current or saved filehandle, it is to be understood that | current or saved filehandle, it is to be understood that | |||
filehandles are only checked for the condition if they | filehandles are only checked for the condition if they | |||
are implicit arguments of the operation in question. | are implicit arguments of the operation in question. | |||
</t> | </t> | |||
<section title="NFS4ERR_BADHANDLE (Error Code 10001)" | <section anchor="err_BADHANDLE" numbered="true" toc="default"> | |||
anchor="err_BADHANDLE"> | <name>NFS4ERR_BADHANDLE (Error Code 10001)</name> | |||
<t> | <t> | |||
Illegal NFS filehandle for the current server. The current | Illegal NFS filehandle for the current server. The current | |||
file handle failed internal consistency checks. Once accepted | filehandle failed internal consistency checks. Once accepted | |||
as valid (by PUTFH), no subsequent status change can cause the | as valid (by PUTFH), no subsequent status change can cause the | |||
filehandle to generate this error. | filehandle to generate this error. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_FHEXPIRED (Error Code 10014)" | <section anchor="err_FHEXPIRED" numbered="true" toc="default"> | |||
anchor="err_FHEXPIRED"> | <name>NFS4ERR_FHEXPIRED (Error Code 10014)</name> | |||
<t> | <t> | |||
A current or saved filehandle that is an argument to the | A current or saved filehandle that is an argument to the | |||
current operation is volatile and has expired at the server. | current operation is volatile and has expired at the server. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_ISDIR (Error Code 21)" | <section anchor="err_ISDIR" numbered="true" toc="default"> | |||
anchor="err_ISDIR"> | <name>NFS4ERR_ISDIR (Error Code 21)</name> | |||
<t> | <t> | |||
The current or saved filehandle designates a directory | The current or saved filehandle designates a directory | |||
when the current operation does not allow a directory to | when the current operation does not allow a directory to | |||
be accepted as the target of this operation. | be accepted as the target of this operation. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_MOVED (Error Code 10019)" | <section anchor="err_MOVED" numbered="true" toc="default"> | |||
anchor="err_MOVED"> | <name>NFS4ERR_MOVED (Error Code 10019)</name> | |||
<t> | <t> | |||
The file system that contains the current filehandle object | The file system that contains the current filehandle object | |||
is not present at the server, or is not accessible using the | is not present at the server or is not accessible with the | |||
network address used. It may have been made accessible on a different | network address used. It may have been made accessible on a different | |||
set of network addresses, relocated or | set of network addresses, relocated or | |||
migrated to another server, or it may have never been present. | migrated to another server, or it may have never been present. | |||
The client may obtain the new file system location by obtaining | The client may obtain the new file system location by obtaining | |||
the "fs_locations" or "fs_locations_info" attribute for the | the fs_locations or fs_locations_info attribute for the | |||
current filehandle. For further discussion, refer to | current filehandle. For further discussion, refer to | |||
<xref target="presence_or_absence" />. | <xref target="presence_or_absence" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
As with the case of NFS4ERR_DELAY, it is possible that one or | As with the case of NFS4ERR_DELAY, it is possible that one or | |||
more non-idempotent operations may have been successfully executed | more non-idempotent operations may have been successfully executed | |||
within a COMPOUND before NFS4ERR_MOVED is returned. Because of | within a COMPOUND before NFS4ERR_MOVED is returned. Because of | |||
this, once the new location is determined, the original request | this, once the new location is determined, the original request | |||
which received the NFS4ERR_MOVED should not be re-executed in full. | that received the NFS4ERR_MOVED should not be re-executed in full. | |||
Instead, the client should send a new COMPOUND, with any successfully | Instead, the client should send a new COMPOUND with any successfully | |||
executed non-idempotent | executed non-idempotent | |||
operations removed. When the client uses the same session for the | operations removed. When the client uses the same session for the | |||
new COMPOUND, its SEQUENCE operation should use a | new COMPOUND, its SEQUENCE operation should use a different slot ID or se | |||
different slot id or sequence. | quence. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_NOFILEHANDLE (Error Code 10020)" | <section anchor="err_NOFILEHANDLE" numbered="true" toc="default"> | |||
anchor="err_NOFILEHANDLE"> | <name>NFS4ERR_NOFILEHANDLE (Error Code 10020)</name> | |||
<t> | <t> | |||
The logical current or saved filehandle value is required by | The logical current or saved filehandle value is required by | |||
the current operation and is not set. | the current operation and is not set. | |||
This may be a result of a malformed COMPOUND | This may be a result of a malformed COMPOUND | |||
operation (i.e., no PUTFH or PUTROOTFH before an operation that | operation (i.e., no PUTFH or PUTROOTFH before an operation that | |||
requires the current filehandle be set). | requires the current filehandle be set). | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_NOTDIR (Error Code 20)" | <section anchor="err_NOTDIR" numbered="true" toc="default"> | |||
anchor="err_NOTDIR"> | <name>NFS4ERR_NOTDIR (Error Code 20)</name> | |||
<t> | <t> | |||
The current (or saved) filehandle designates an object that | The current (or saved) filehandle designates an object that | |||
is not a directory for an operation in which a directory is | is not a directory for an operation in which a directory is | |||
required. | required. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_STALE (Error Code 70)" | <section anchor="err_STALE" numbered="true" toc="default"> | |||
anchor="err_STALE"> | <name>NFS4ERR_STALE (Error Code 70)</name> | |||
<t> | <t> | |||
The current or saved filehandle value designating an argument | The current or saved filehandle value designating an argument | |||
to the current operation is invalid. The file referred to by | to the current operation is invalid. The file referred to by | |||
that filehandle no longer exists or access to it has been | that filehandle no longer exists or access to it has been | |||
revoked. | revoked. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_SYMLINK (Error Code 10029)" | <section anchor="err_SYMLINK" numbered="true" toc="default"> | |||
anchor="err_SYMLINK"> | <name>NFS4ERR_SYMLINK (Error Code 10029)</name> | |||
<t> | <t> | |||
The current filehandle designates a symbolic link when the | The current filehandle designates a symbolic link when the | |||
current operation does not allow a symbolic link as the | current operation does not allow a symbolic link as the | |||
target. | target. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_WRONG_TYPE (Error Code 10083)" | <section anchor="err_WRONG_TYPE" numbered="true" toc="default"> | |||
anchor="err_WRONG_TYPE"> | <name>NFS4ERR_WRONG_TYPE (Error Code 10083)</name> | |||
<t> | <t> | |||
The current (or saved) filehandle designates an object that | The current (or saved) filehandle designates an object that | |||
is of an invalid type for the current operation, and there is no | is of an invalid type for the current operation, and there is no | |||
more specific error (such as NFS4ERR_ISDIR or NFS4ERR_SYMLINK) | more specific error (such as NFS4ERR_ISDIR or NFS4ERR_SYMLINK) | |||
that applies. Note that in NFSv4.0, such situations generally | that applies. Note that in NFSv4.0, such situations generally | |||
resulted in the less-specific error NFS4ERR_INVAL. | resulted in the less-specific error NFS4ERR_INVAL. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="errors_comp" numbered="true" toc="default"> | ||||
<section title="Compound Structure Errors" anchor="errors_comp"> | <name>Compound Structure Errors</name> | |||
<t> | <t> | |||
This section deals with errors that relate to the overall structure | This section deals with errors that relate to the overall structure | |||
of a Compound request (by which we mean to include both | of a Compound request (by which we mean to include both | |||
COMPOUND and CB_COMPOUND), rather than to particular operations. | COMPOUND and CB_COMPOUND), rather than to particular operations. | |||
</t> | </t> | |||
<t> | <t> | |||
There are a number of basic constraints on the operations that | There are a number of basic constraints on the operations that | |||
may appear in a Compound request. Sessions add to these basic | may appear in a Compound request. Sessions add to these basic | |||
constraints by requiring a Sequence operation (either SEQUENCE | constraints by requiring a Sequence operation (either SEQUENCE | |||
or CB_SEQUENCE) at the start of the Compound. | or CB_SEQUENCE) at the start of the Compound. | |||
</t> | </t> | |||
<section title="NFS_OK (Error code 0)" | <section anchor="err_OK" numbered="true" toc="default"> | |||
anchor="err_OK"> | <name>NFS_OK (Error code 0)</name> | |||
<t> | <t> | |||
Indicates the operation completed successfully, in that all | Indicates the operation completed successfully, in that all | |||
of the constituent operations completed without error. | of the constituent operations completed without error. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_MINOR_VERS_MISMATCH (Error code 10021)" | <section anchor="err_MINOR_VERS_MISMATCH" numbered="true" toc="default | |||
anchor="err_MINOR_VERS_MISMATCH"> | "> | |||
<t> | <name>NFS4ERR_MINOR_VERS_MISMATCH (Error code 10021)</name> | |||
<t> | ||||
The minor version specified is not one that the current listener | The minor version specified is not one that the current listener | |||
supports. This value is returned in the overall status for the | supports. This value is returned in the overall status for the | |||
Compound but is not associated with a specific operation since | Compound but is not associated with a specific operation since | |||
the results will specify a result count of zero. | the results will specify a result count of zero. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_NOT_ONLY_OP (Error Code 10081)" | <section anchor="err_NOT_ONLY_OP" numbered="true" toc="default"> | |||
anchor="err_NOT_ONLY_OP"> | <name>NFS4ERR_NOT_ONLY_OP (Error Code 10081)</name> | |||
<t> | <t> | |||
Certain operations, which are allowed to be executed outside | Certain operations, which are allowed to be executed outside | |||
of a session, MUST be the only operation within a Compound | of a session, <bcp14>MUST</bcp14> be the only operation within a Compoun d | |||
whenever the Compound does not start with a Sequence | whenever the Compound does not start with a Sequence | |||
operation. This error results when that constraint is not met. | operation. This error results when that constraint is not met. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_OP_ILLEGAL (Error Code 10044)" | <section anchor="err_OP_ILLEGAL" numbered="true" toc="default"> | |||
anchor="err_OP_ILLEGAL"> | <name>NFS4ERR_OP_ILLEGAL (Error Code 10044)</name> | |||
<t> | <t> | |||
The operation code is not a valid one for the current | The operation code is not a valid one for the current | |||
Compound procedure. The opcode | Compound procedure. The opcode | |||
in the result stream matched with this error is the | in the result stream matched with this error is the | |||
ILLEGAL value, although the value that appears in the | ILLEGAL value, although the value that appears in the | |||
request stream may be different. Where an illegal | request stream may be different. Where an illegal | |||
value appears and the replier pre-parses all operations for | value appears and the replier pre-parses all operations for | |||
a Compound procedure before doing any operation execution, | a Compound procedure before doing any operation execution, | |||
an RPC-level XDR error may be returned. | an RPC-level XDR error may be returned. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_OP_NOT_IN_SESSION (Error Code 10071)" | <section anchor="err_OP_NOT_IN_SESSION" numbered="true" toc="default"> | |||
anchor="err_OP_NOT_IN_SESSION"> | <name>NFS4ERR_OP_NOT_IN_SESSION (Error Code 10071)</name> | |||
<t> | <t> | |||
Most forward operations and all callback operations are only | Most forward operations and all callback operations are only | |||
valid within the context of a session, so that the Compound | valid within the context of a session, so that the Compound | |||
request in question MUST begin with a Sequence operation. | request in question <bcp14>MUST</bcp14> begin with a Sequence operation. | |||
If an attempt is made to execute these operations outside | If an attempt is made to execute these operations outside | |||
the context of session, this error results. | the context of session, this error results. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_REP_TOO_BIG (Error Code 10066)" | <section anchor="err_REP_TOO_BIG" numbered="true" toc="default"> | |||
anchor="err_REP_TOO_BIG"> | <name>NFS4ERR_REP_TOO_BIG (Error Code 10066)</name> | |||
<t> | <t> | |||
The reply to a Compound would exceed the | The reply to a Compound would exceed the | |||
channel's negotiated maximum response size. | channel's negotiated maximum response size. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_REP_TOO_BIG_TO_CACHE (Error Code 10067)" | <section anchor="err_REP_TOO_BIG_TO_CACHE" numbered="true" toc="defaul | |||
anchor="err_REP_TOO_BIG_TO_CACHE"> | t"> | |||
<t> | <name>NFS4ERR_REP_TOO_BIG_TO_CACHE (Error Code 10067)</name> | |||
<t> | ||||
The reply to a Compound would exceed the | The reply to a Compound would exceed the | |||
channel's negotiated maximum size for replies cached in the | channel's negotiated maximum size for replies cached in the | |||
reply cache when the Sequence for the current request specifies | reply cache when the Sequence for the current request specifies | |||
that this request is to be cached. | that this request is to be cached. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_REQ_TOO_BIG (Error Code 10065)" | <section anchor="err_REQ_TOO_BIG" numbered="true" toc="default"> | |||
anchor="err_REQ_TOO_BIG"> | <name>NFS4ERR_REQ_TOO_BIG (Error Code 10065)</name> | |||
<t> | <t> | |||
The Compound request exceeds the | The Compound request exceeds the | |||
channel's negotiated maximum size for requests. | channel's negotiated maximum size for requests. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_RETRY_UNCACHED_REP (Error Code 10068)" | <section anchor="err_RETRY_UNCACHED_REP" numbered="true" toc="default" | |||
anchor="err_RETRY_UNCACHED_REP"> | > | |||
<t> | <name>NFS4ERR_RETRY_UNCACHED_REP (Error Code 10068)</name> | |||
<t> | ||||
The requester has attempted a retry of a Compound | The requester has attempted a retry of a Compound | |||
that it previously requested not | that it previously requested not | |||
be placed in the reply cache. | be placed in the reply cache. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_SEQUENCE_POS (Error Code 10064)" | <section anchor="err_SEQUENCE_POS" numbered="true" toc="default"> | |||
anchor="err_SEQUENCE_POS"> | <name>NFS4ERR_SEQUENCE_POS (Error Code 10064)</name> | |||
<t> | <t> | |||
A Sequence operation appeared in a | A Sequence operation appeared in a | |||
position other than the first operation of a | position other than the first operation of a | |||
Compound request. | Compound request. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_TOO_MANY_OPS (Error Code 10070)" | <section anchor="err_TOO_MANY_OPS" numbered="true" toc="default"> | |||
anchor="err_TOO_MANY_OPS"> | <name>NFS4ERR_TOO_MANY_OPS (Error Code 10070)</name> | |||
<t> | <t> | |||
The Compound request has too many operations, exceeding the | The Compound request has too many operations, exceeding the | |||
count negotiated when the session was created. | count negotiated when the session was created. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_UNSAFE_COMPOUND (Error Code 10068)" | <section anchor="err_UNSAFE_COMPOUND" numbered="true" toc="default"> | |||
anchor="err_UNSAFE_COMPOUND"> | <name>NFS4ERR_UNSAFE_COMPOUND (Error Code 10068)</name> | |||
<t> | <t> | |||
The client has sent a COMPOUND request with an unsafe | The client has sent a COMPOUND request with an unsafe | |||
mix of operations -- specifically, with a non-idempotent | mix of operations -- specifically, with a non-idempotent | |||
operation that changes the current filehandle and that is not followed b y a | operation that changes the current filehandle and that is not followed b y a | |||
GETFH. | GETFH. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="errors_fs" numbered="true" toc="default"> | ||||
<section title="File System Errors" anchor="errors_fs"> | <name>File System Errors</name> | |||
<t> | <t> | |||
These errors describe situations that occurred in the underlying | These errors describe situations that occurred in the underlying | |||
file system implementation rather than in the protocol or any | file system implementation rather than in the protocol or any | |||
NFSv4.x feature. | NFSv4.x feature. | |||
</t> | </t> | |||
<section title="NFS4ERR_BADTYPE (Error Code 10007)" | <section anchor="err_BADTYPE" numbered="true" toc="default"> | |||
anchor="err_BADTYPE"> | <name>NFS4ERR_BADTYPE (Error Code 10007)</name> | |||
<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 title="NFS4ERR_DQUOT (Error Code 19)" | <section anchor="err_DQUOT" numbered="true" toc="default"> | |||
anchor="err_DQUOT"> | <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 title="NFS4ERR_EXIST (Error Code 17)" | <section anchor="err_EXIST" numbered="true" toc="default"> | |||
anchor="err_EXIST"> | <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. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_FBIG (Error Code 27)" | <section anchor="err_FBIG" numbered="true" toc="default"> | |||
anchor="err_FBIG"> | <name>NFS4ERR_FBIG (Error Code 27)</name> | |||
<t> | <t> | |||
The file is too large. The operation would have caused the file to | The file is too large. The operation would have caused the file to | |||
grow beyond the server's limit. | grow beyond the server's limit. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_FILE_OPEN (Error Code 10046)" | <section anchor="err_FILE_OPEN" numbered="true" toc="default"> | |||
anchor="err_FILE_OPEN"> | <name>NFS4ERR_FILE_OPEN (Error Code 10046)</name> | |||
<t> | <t> | |||
The operation is not allowed because a | The operation is not allowed because a | |||
file involved in the operation is currently open. | file involved in the operation is currently open. | |||
Servers may, but are not required to, disallow linking-to, | Servers may, but are not required to, disallow linking-to, | |||
removing, or renaming open files. | removing, or renaming open files. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_IO (Error Code 5)" | <section anchor="err_IO" numbered="true" toc="default"> | |||
anchor="err_IO"> | <name>NFS4ERR_IO (Error Code 5)</name> | |||
<t> | <t> | |||
Indicates that an I/O error occurred for which the file system | Indicates that an I/O error occurred for which the file system | |||
was unable to provide recovery. | was unable to provide recovery. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_MLINK (Error Code 31)" | <section anchor="err_MLINK" numbered="true" toc="default"> | |||
anchor="err_MLINK"> | <name>NFS4ERR_MLINK (Error Code 31)</name> | |||
<t> | <t> | |||
The request would have caused the server's limit for the | The request would have caused the server's limit for the | |||
number of hard links a file may have to be exceeded. | number of hard links a file may have to be exceeded. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_NOENT (Error Code 2)" | <section anchor="err_NOENT" numbered="true" toc="default"> | |||
anchor="err_NOENT"> | <name>NFS4ERR_NOENT (Error Code 2)</name> | |||
<t> | <t> | |||
Indicates no such file or directory. The file or directory name | Indicates no such file or directory. The file or directory name | |||
specified does not exist. | specified does not exist. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_NOSPC (Error Code 28)" | <section anchor="err_NOSPC" numbered="true" toc="default"> | |||
anchor="err_NOSPC"> | <name>NFS4ERR_NOSPC (Error Code 28)</name> | |||
<t> | <t> | |||
Indicates there is no space left on the device. The operation would have | Indicates there is no space left on the device. The operation would have | |||
caused the server's file system to exceed its limit. | caused the server's file system to exceed its limit. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_NOTEMPTY (Error Code 66)" | <section anchor="err_NOTEMPTY" numbered="true" toc="default"> | |||
anchor="err_NOTEMPTY"> | <name>NFS4ERR_NOTEMPTY (Error Code 66)</name> | |||
<t> | <t> | |||
An attempt was made to remove a directory that was not | An attempt was made to remove a directory that was not | |||
empty. | empty. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_ROFS (Error Code 30)" | <section anchor="err_ROFS" numbered="true" toc="default"> | |||
anchor="err_ROFS"> | <name>NFS4ERR_ROFS (Error Code 30)</name> | |||
<t> | <t> | |||
Indicates a read-only file system. A modifying operation was | Indicates a read-only file system. A modifying operation was | |||
attempted on a read-only file system. | attempted on a read-only file system. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_XDEV (Error Code 18)" | <section anchor="err_XDEV" numbered="true" toc="default"> | |||
anchor="err_XDEV"> | <name>NFS4ERR_XDEV (Error Code 18)</name> | |||
<t> | <t> | |||
Indicates an attempt to do an operation, such as linking, that | Indicates an attempt to do an operation, such as linking, that | |||
inappropriately crosses a boundary. This may be due to such | inappropriately crosses a boundary. This may be due to such | |||
boundaries as: | boundaries as: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
that between file systems (where the fsids are different). | that between file systems (where the fsids are different). | |||
</t> | </li> | |||
<t> | <li> | |||
that between different named attribute directories or | that between different named attribute directories or | |||
between a named attribute directory and an ordinary | between a named attribute directory and an ordinary | |||
directory. | directory. | |||
</t> | </li> | |||
<t> | <li> | |||
that between byte-ranges of a file system that the file system | that between byte-ranges of a file system that the file system | |||
implementation treats as separate (for example, for space | implementation treats as separate (for example, for space | |||
accounting purposes), and where cross-connection between | accounting purposes), and where cross-connection between | |||
the byte-ranges are not allowed. | the byte-ranges are not allowed. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="errors_state_mgt" numbered="true" toc="default"> | |||
<name>State Management Errors</name> | ||||
<section title="State Management Errors" anchor="errors_state_mgt"> | <t> | |||
<t> | ||||
These errors indicate problems with the stateid (or one of | These errors indicate problems with the stateid (or one of | |||
the stateids) passed to a given operation. | the stateids) passed to a given operation. | |||
This includes | This includes | |||
situations in which the stateid is invalid as well as | situations in which the stateid is invalid as well as | |||
situations in which the stateid is valid but designates | situations in which the stateid is valid but designates | |||
locking state that has been revoked. | locking state that has been revoked. | |||
Depending on the operation, the | Depending on the operation, the | |||
stateid when valid may designate opens, byte-range locks, | stateid when valid may designate opens, byte-range locks, | |||
file or directory delegations, layouts, or device maps. | file or directory delegations, layouts, or device maps. | |||
</t> | </t> | |||
<section title="NFS4ERR_ADMIN_REVOKED (Error Code 10047)" | <section anchor="err_ADMIN_REVOKED" numbered="true" toc="default"> | |||
anchor="err_ADMIN_REVOKED"> | <name>NFS4ERR_ADMIN_REVOKED (Error Code 10047)</name> | |||
<t> | <t> | |||
A stateid designates locking state of any type that has | A stateid designates locking state of any type that has | |||
been revoked due to administrative interaction, possibly | been revoked due to administrative interaction, possibly | |||
while the lease is valid. | while the lease is valid. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_BAD_STATEID (Error Code 10026)" | <section anchor="err_BAD_STATEID" numbered="true" toc="default"> | |||
anchor="err_BAD_STATEID"> | <name>NFS4ERR_BAD_STATEID (Error Code 10026)</name> | |||
<t> | <t> | |||
A stateid does not properly designate any valid | A stateid does not properly designate any valid | |||
state. See Sections <xref target="stateid_lifetime" format="counter" /> | state. See Sections <xref target="stateid_lifetime" format="counter"/> | |||
and | and | |||
<xref target="special_stateid" format="counter" /> | <xref target="special_stateid" format="counter"/> | |||
for a discussion of how stateids are validated. | for a discussion of how stateids are validated. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_DELEG_REVOKED (Error Code 10087)" | <section anchor="err_DELEG_REVOKED" numbered="true" toc="default"> | |||
anchor="err_DELEG_REVOKED"> | <name>NFS4ERR_DELEG_REVOKED (Error Code 10087)</name> | |||
<t> | <t> | |||
A stateid designates recallable locking state of | A stateid designates recallable locking state of | |||
any type (delegation or layout) that has been | any type (delegation or layout) that has been | |||
revoked due to the failure of the client to return | revoked due to the failure of the client to return | |||
the lock when it was recalled. | the lock when it was recalled. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_EXPIRED (Error Code 10011)" | <section anchor="err_EXPIRED" numbered="true" toc="default"> | |||
anchor="err_EXPIRED"> | <name>NFS4ERR_EXPIRED (Error Code 10011)</name> | |||
<t> | <t> | |||
A stateid designates locking state of any type that has | A stateid designates locking state of any type that has | |||
been revoked due to expiration of the client's lease, | been revoked due to expiration of the client's lease, | |||
either immediately upon lease expiration, or following | either immediately upon lease expiration, or following | |||
a later request for a conflicting lock. | a later request for a conflicting lock. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_OLD_STATEID (Error Code 10024)" | <section anchor="err_OLD_STATEID" numbered="true" toc="default"> | |||
anchor="err_OLD_STATEID"> | <name>NFS4ERR_OLD_STATEID (Error Code 10024)</name> | |||
<t> | <t> | |||
A stateid with a non-zero seqid value does match | A stateid with a non-zero seqid value does match | |||
the current seqid for the state designated by the | the current seqid for the state designated by the | |||
user. | user. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="errors_sec" numbered="true" toc="default"> | ||||
<section title="Security Errors" anchor="errors_sec"> | <name>Security Errors</name> | |||
<t> | <t> | |||
These are the various permission-related errors in NFSv4.1. | These are the various permission-related errors in NFSv4.1. | |||
</t> | </t> | |||
<section title="NFS4ERR_ACCESS (Error Code 13)" | <section anchor="err_ACCESS" numbered="true" toc="default"> | |||
anchor="err_ACCESS"> | <name>NFS4ERR_ACCESS (Error Code 13)</name> | |||
<t> | <t> | |||
Indicates permission denied. The caller does | Indicates permission denied. The caller does | |||
not have the correct permission to perform | not have the correct permission to perform | |||
the requested operation. Contrast this with | the requested operation. Contrast this with | |||
NFS4ERR_PERM (<xref target="err_PERM" />), which | NFS4ERR_PERM (<xref target="err_PERM" format="default"/>), which | |||
restricts itself to owner or privileged-user | restricts itself to owner or privileged-user | |||
permission failures, and NFS4ERR_WRONG_CRED | permission failures, and NFS4ERR_WRONG_CRED | |||
(<xref target="err_WRONG_CRED" />), which deals | (<xref target="err_WRONG_CRED" format="default"/>), which deals | |||
with appropriate permission to delete or modify | with appropriate permission to delete or modify | |||
transient objects based on the credentials of | transient objects based on the credentials of | |||
the user that created them. | the user that created them. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_PERM (Error Code 1)" | <section anchor="err_PERM" numbered="true" toc="default"> | |||
anchor="err_PERM"> | <name>NFS4ERR_PERM (Error Code 1)</name> | |||
<t> | <t> | |||
Indicates requester is not the owner. The operation was not | Indicates requester is not the owner. The operation was not | |||
allowed because the caller is neither a privileged user | allowed because the caller is neither a privileged user | |||
(root) nor the owner of the target of the operation. | (root) nor the owner of the target of the operation. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_WRONGSEC (Error Code 10016)" | <section anchor="err_WRONGSEC" numbered="true" toc="default"> | |||
anchor="err_WRONGSEC"> | <name>NFS4ERR_WRONGSEC (Error Code 10016)</name> | |||
<t> | <t> | |||
Indicates that the security mechanism being used by the client | Indicates that the security mechanism being used by the client | |||
for the operation does not match the server's security policy. | for the operation does not match the server's security policy. | |||
The client should change the security mechanism being used and | The client should change the security mechanism being used and | |||
re-send the operation (but not with the same slot ID and | re-send the operation (but not with the same slot ID and | |||
sequence ID; one or both MUST be different on the re-send). SECINFO and SECINFO_NO_NAME can be used | sequence ID; one or both <bcp14>MUST</bcp14> be different on the re-send ). SECINFO and SECINFO_NO_NAME can be used | |||
to determine the appropriate mechanism. | to determine the appropriate mechanism. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_WRONG_CRED (Error Code 10082)" | <section anchor="err_WRONG_CRED" numbered="true" toc="default"> | |||
anchor="err_WRONG_CRED"> | <name>NFS4ERR_WRONG_CRED (Error Code 10082)</name> | |||
<t> | <t> | |||
An operation that manipulates state was attempted by a principal | An operation that manipulates state was attempted by a principal | |||
that was not allowed to modify that piece of state. | that was not allowed to modify that piece of state. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="errors_name" numbered="true" toc="default"> | ||||
<section title="Name Errors" anchor="errors_name"> | <name>Name Errors</name> | |||
<t> | <t> | |||
Names in NFSv4 are UTF-8 strings. When the strings are not | Names in NFSv4 are UTF-8 strings. When the strings are not | |||
valid UTF-8 or are of length zero, the error NFS4ERR_INVAL | valid UTF-8 or are of length zero, the error NFS4ERR_INVAL | |||
results. Besides this, there are a number of other errors | results. Besides this, there are a number of other errors | |||
to indicate specific problems with names. | to indicate specific problems with names. | |||
</t> | </t> | |||
<section title="NFS4ERR_BADCHAR (Error Code 10040)" | <section anchor="err_BADCHAR" numbered="true" toc="default"> | |||
anchor="err_BADCHAR"> | <name>NFS4ERR_BADCHAR (Error Code 10040)</name> | |||
<t> | <t> | |||
A UTF-8 string contains a character that is not supported | A UTF-8 string contains a character that is not supported | |||
by the server in the context in which it being used. | by the server in the context in which it being used. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_BADNAME (Error Code 10041)" | <section anchor="err_BADNAME" numbered="true" toc="default"> | |||
anchor="err_BADNAME"> | <name>NFS4ERR_BADNAME (Error Code 10041)</name> | |||
<t> | <t> | |||
A name string in a request consisted of valid UTF-8 | A name string in a request consisted of valid UTF-8 | |||
characters supported by the server, but the name is not | characters supported by the server, but the name is not | |||
supported by the server as a valid name for the current operation. | supported by the server as a valid name for the current operation. | |||
An example might be creating a file or directory named ".." | An example might be creating a file or directory named ".." | |||
on a server whose file system uses that name for links to | on a server whose file system uses that name for links to | |||
parent directories. | parent directories. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_NAMETOOLONG (Error Code 63)" | <section anchor="err_NAMETOOLONG" numbered="true" toc="default"> | |||
anchor="err_NAMETOOLONG"> | <name>NFS4ERR_NAMETOOLONG (Error Code 63)</name> | |||
<t> | <t> | |||
Returned when the filename in an operation exceeds the | Returned when the filename in an operation exceeds the | |||
server's implementation limit. | server's implementation limit. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="errors_locking" numbered="true" toc="default"> | ||||
<section title="Locking Errors" anchor="errors_locking"> | <name>Locking Errors</name> | |||
<t> | <t> | |||
This section deals with errors related to locking, both as to | This section deals with errors related to locking, both as to | |||
share reservations and byte-range locking. It does not deal | share reservations and byte-range locking. It does not deal | |||
with errors specific to the process of reclaiming locks. Those | with errors specific to the process of reclaiming locks. Those | |||
are dealt with in <xref target="errors_reclaim"></xref>. | are dealt with in <xref target="errors_reclaim" format="default"/>. | |||
</t> | </t> | |||
<section title="NFS4ERR_BAD_RANGE (Error Code 10042)" | <section anchor="err_BAD_RANGE" numbered="true" toc="default"> | |||
anchor="err_BAD_RANGE"> | <name>NFS4ERR_BAD_RANGE (Error Code 10042)</name> | |||
<t> | <t> | |||
The byte-range of a LOCK, LOCKT, or LOCKU operation is | The byte-range of a LOCK, LOCKT, or LOCKU operation is | |||
not allowed by the | not allowed by the | |||
server. For example, this error results when a server | server. For example, this error results when a server | |||
that only supports 32-bit ranges receives a range that | that only supports 32-bit ranges receives a range that | |||
cannot be handled by that server. (See | cannot be handled by that server. (See | |||
<xref target="OP_LOCK_DESCRIPTION" />.) | <xref target="OP_LOCK_DESCRIPTION" format="default"/>.) | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_DEADLOCK (Error Code 10045)" | <section anchor="err_DEADLOCK" numbered="true" toc="default"> | |||
anchor="err_DEADLOCK"> | <name>NFS4ERR_DEADLOCK (Error Code 10045)</name> | |||
<t> | <t> | |||
The server has been able to determine a byte-range locking | The server has been able to determine a byte-range locking | |||
deadlock condition for a READW_LT or WRITEW_LT LOCK operation. | deadlock condition for a READW_LT or WRITEW_LT LOCK operation. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_DENIED (Error Code 10010)" | <section anchor="err_DENIED" numbered="true" toc="default"> | |||
anchor="err_DENIED"> | <name>NFS4ERR_DENIED (Error Code 10010)</name> | |||
<t> | <t> | |||
An attempt to lock a file is denied. Since this may be a | An attempt to lock a file is denied. Since this may be a | |||
temporary condition, the client is encouraged to re-send the lock | temporary condition, the client is encouraged to re-send the lock | |||
request (but not with the same slot ID and | request (but not with the same slot ID and | |||
sequence ID; one or both MUST be different on the re-send) until the loc | sequence ID; one or both <bcp14>MUST</bcp14> be different on the re-send | |||
k is accepted. See | ) until the lock is accepted. See | |||
<xref target="blocking_locks" /> for a discussion of the re-send. | <xref target="blocking_locks" format="default"/> for a discussion of the | |||
</t> | re-send. | |||
</section> | </t> | |||
<section title="NFS4ERR_LOCKED (Error Code 10012)" | </section> | |||
anchor="err_LOCKED"> | <section anchor="err_LOCKED" numbered="true" toc="default"> | |||
<t> | <name>NFS4ERR_LOCKED (Error Code 10012)</name> | |||
<t> | ||||
A READ or WRITE operation was attempted on a file where there | A READ or WRITE operation was attempted on a file where there | |||
was a conflict between the I/O and an existing lock: | was a conflict between the I/O and an existing lock: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
There is a share reservation inconsistent with the I/O | There is a share reservation inconsistent with the I/O | |||
being done. | being done. | |||
</t> | </li> | |||
<t> | <li> | |||
The range to be read or written intersects an existing | The range to be read or written intersects an existing | |||
mandatory byte-range lock. | mandatory byte-range lock. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section anchor="err_LOCKS_HELD" numbered="true" toc="default"> | |||
<section title="NFS4ERR_LOCKS_HELD (Error Code 10037)" | <name>NFS4ERR_LOCKS_HELD (Error Code 10037)</name> | |||
anchor="err_LOCKS_HELD"> | <t> | |||
<t> | ||||
An operation was prevented by the unexpected presence of locks. | An operation was prevented by the unexpected presence of locks. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_LOCK_NOTSUPP (Error Code 10043)" | <section anchor="err_LOCK_NOTSUPP" numbered="true" toc="default"> | |||
anchor="err_LOCK_NOTSUPP"> | <name>NFS4ERR_LOCK_NOTSUPP (Error Code 10043)</name> | |||
<t> | <t> | |||
A LOCK operation was attempted that would require the upgrade | A LOCK operation was attempted that would require the upgrade | |||
or downgrade of a byte-range lock range already held by the owner, and t he | or downgrade of a byte-range lock range already held by the owner, and t he | |||
server does not support atomic upgrade or downgrade of locks. | server does not support atomic upgrade or downgrade of locks. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_LOCK_RANGE (Error Code 10028)" | <section anchor="err_LOCK_RANGE" numbered="true" toc="default"> | |||
anchor="err_LOCK_RANGE"> | <name>NFS4ERR_LOCK_RANGE (Error Code 10028)</name> | |||
<t> | <t> | |||
A LOCK operation is operating on a range that overlaps in part a | A LOCK operation is operating on a range that overlaps in part a | |||
currently held byte-range lock for the current lock-owner and does not | currently held byte-range lock for the current lock-owner and does not | |||
precisely match a single such byte-range lock where the server | precisely match a single such byte-range lock where the server | |||
does not support this type of request, and thus does not | does not support this type of request, and thus does not | |||
implement POSIX locking semantics <xref target="fcntl"/>. See Sections | implement POSIX locking semantics <xref target="fcntl" format="default"/ | |||
<xref target="OP_LOCK_IMPLEMENTATION" format="counter" />, | >. See Sections | |||
<xref target="OP_LOCKT_IMPLEMENTATION" format="counter" />, and | <xref target="OP_LOCK_IMPLEMENTATION" format="counter"/>, | |||
<xref target="OP_LOCKU_IMPLEMENTATION" format="counter" /> for a discuss | <xref target="OP_LOCKT_IMPLEMENTATION" format="counter"/>, and | |||
ion of | <xref target="OP_LOCKU_IMPLEMENTATION" format="counter"/> for a discussi | |||
on of | ||||
how this applies to LOCK, LOCKT, and LOCKU respectively. | how this applies to LOCK, LOCKT, and LOCKU respectively. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_OPENMODE (Error Code 10038)" | <section anchor="err_OPENMODE" numbered="true" toc="default"> | |||
anchor="err_OPENMODE"> | <name>NFS4ERR_OPENMODE (Error Code 10038)</name> | |||
<t> | <t> | |||
The client attempted a READ, WRITE, LOCK, or other operation | The client attempted a READ, WRITE, LOCK, or other operation | |||
not sanctioned by the stateid passed (e.g., writing to a file | not sanctioned by the stateid passed (e.g., writing to a file | |||
opened for read-only access). | opened for read-only access). | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_SHARE_DENIED (Error Code 10015)" | <section anchor="err_SHARE_DENIED" numbered="true" toc="default"> | |||
anchor="err_SHARE_DENIED"> | <name>NFS4ERR_SHARE_DENIED (Error Code 10015)</name> | |||
<t> | <t> | |||
An attempt to OPEN a file with a share reservation has failed | An attempt to OPEN a file with a share reservation has failed | |||
because of a share conflict. | because of a share conflict. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="errors_reclaim" numbered="true" toc="default"> | ||||
<section title="Reclaim Errors" anchor="errors_reclaim"> | <name>Reclaim Errors</name> | |||
<t> | <t> | |||
These errors relate to the process of reclaiming locks after a | These errors relate to the process of reclaiming locks after a | |||
server restart. | server restart. | |||
</t> | </t> | |||
<section title="NFS4ERR_COMPLETE_ALREADY (Error Code 10054)" | <section anchor="err_COMPLETE_ALREADY" numbered="true" toc="default"> | |||
anchor="err_COMPLETE_ALREADY"> | <name>NFS4ERR_COMPLETE_ALREADY (Error Code 10054)</name> | |||
<t> | <t> | |||
The client previously sent a successful RECLAIM_COMPLETE | The client previously sent a successful RECLAIM_COMPLETE | |||
operation specifying the same scope, whether that scope is global | operation specifying the same scope, whether that scope is global | |||
or for the same file system in the case of a per-fs RECLAIM_COMPLETE. | or for the same file system in the case of a per-fs RECLAIM_COMPLETE. | |||
An additional RECLAIM_COMPLETE operation is not | An additional RECLAIM_COMPLETE operation is not necessary and results in | |||
necessary and results in this error. | this error. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_GRACE (Error Code 10013)" | <section anchor="err_GRACE" numbered="true" toc="default"> | |||
anchor="err_GRACE"> | <name>NFS4ERR_GRACE (Error Code 10013)</name> | |||
<t> | <t> | |||
This error is returned when the server is in its | This error is returned when the server is in its | |||
grace period with regard to the file system object for which | grace period with regard to the file system object for which | |||
the lock was requested. In this situation, a non-reclaim | the lock was requested. In this situation, a non-reclaim | |||
locking request cannot be granted. This can occur because either | locking request cannot be granted. This can occur because either: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The server does not have sufficient information about locks that | The server does not have sufficient information about locks that | |||
might be potentially reclaimed to determine whether the lock could | might be potentially reclaimed to determine whether the lock could | |||
be granted. | be granted. | |||
</t> | </li> | |||
<t> | <li> | |||
The request is made by a client responsible for reclaiming its | The request is made by a client responsible for reclaiming its | |||
locks that has not yet done the appropriate RECLAIM_COMPLETE | locks that has not yet done the appropriate RECLAIM_COMPLETE | |||
operation, allowing it to proceed to obtain new locks. | operation, allowing it to proceed to obtain new locks. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
In the case of a per-fs grace period, | In the case of a per-fs grace period, | |||
there may be clients, (i.e., those currently using the destination | there may be clients (i.e., those currently using the destination | |||
file system) who might be unaware of the circumstances resulting | file system) who might be unaware of the circumstances resulting | |||
in the initiation of the grace period. Such clients need to | in the initiation of the grace period. Such clients need to | |||
periodically retry the request until the grace period is over, just as | periodically retry the request until the grace period is over, just as | |||
other clients do. | other clients do. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_NO_GRACE (Error Code 10033)" | <section anchor="err_NO_GRACE" numbered="true" toc="default"> | |||
anchor="err_NO_GRACE"> | <name>NFS4ERR_NO_GRACE (Error Code 10033)</name> | |||
<t> | <t> | |||
A reclaim of client state was attempted in circumstances in | A reclaim of client state was attempted in circumstances in | |||
which the server cannot guarantee that conflicting state has | which the server cannot guarantee that conflicting state has | |||
not been provided to another client. This occurs in any of the | not been provided to another client. This occurs in any of the | |||
following situations. | following situations: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
There | There | |||
is no active grace period applying to the file system object | is no active grace period applying to the file system object | |||
for which the request was made. | for which the request was made. | |||
</t> | </li> | |||
<t> | <li> | |||
The client making the | The client making the | |||
request has no current role in reclaiming locks. | request has no current role in reclaiming locks. | |||
</t> | </li> | |||
<t> | <li> | |||
Previous operations have created a situation in which | Previous operations have created a situation in which | |||
the server is not able to determine that a reclaim-interfering | the server is not able to determine that a reclaim-interfering | |||
edge condition does not exist. | edge condition does not exist. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section anchor="err_RECLAIM_BAD" numbered="true" toc="default"> | |||
<section title="NFS4ERR_RECLAIM_BAD (Error Code 10034)" | <name>NFS4ERR_RECLAIM_BAD (Error Code 10034)</name> | |||
anchor="err_RECLAIM_BAD"> | <t> | |||
<t> | ||||
The server has determined that a reclaim attempted by the client | The server has determined that a reclaim attempted by the client | |||
is not valid, i.e. the lock specified as being reclaimed could | is not valid, i.e., the lock specified as being reclaimed could | |||
not possibly have existed before the server restart or file | not possibly have existed before the server restart or file | |||
system migration event. A server | system migration event. A server | |||
is not obliged to make this determination and will typically rely | is not obliged to make this determination and will typically rely | |||
on the client to only reclaim locks that the client was granted prior | on the client to only reclaim locks that the client was granted prior | |||
to restart. However, | to restart. However, | |||
when a server does have reliable information to enable it to make | when a server does have reliable information to enable it to make | |||
this determination, this error indicates that the reclaim has | this determination, this error indicates that the reclaim has | |||
been rejected as invalid. This is as opposed to the error | been rejected as invalid. This is as opposed to the error | |||
NFS4ERR_RECLAIM_CONFLICT (see <xref target="err_RECLAIM_CONFLICT"/>) | NFS4ERR_RECLAIM_CONFLICT (see <xref target="err_RECLAIM_CONFLICT" format= "default"/>) | |||
where the server can only determine that | where the server can only determine that | |||
there has been an invalid reclaim, but cannot determine | there has been an invalid reclaim, but cannot determine | |||
which request is invalid. | which request is invalid. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_RECLAIM_CONFLICT (Error Code 10035)" | <section anchor="err_RECLAIM_CONFLICT" numbered="true" toc="default"> | |||
anchor="err_RECLAIM_CONFLICT"> | <name>NFS4ERR_RECLAIM_CONFLICT (Error Code 10035)</name> | |||
<t> | <t> | |||
The reclaim attempted by the client has encountered a conflict | The reclaim attempted by the client has encountered a conflict | |||
and cannot be satisfied. This potentially indicates a misbehaving | and cannot be satisfied. This potentially indicates a misbehaving | |||
client, although not necessarily the one receiving the error. | client, although not necessarily the one receiving the error. | |||
The misbehavior might be on the part of the client that | The misbehavior might be on the part of the client that | |||
established the lock with which this client conflicted. See also | established the lock with which this client conflicted. See also | |||
<xref target="err_RECLAIM_BAD"/> for the related error, | <xref target="err_RECLAIM_BAD" format="default"/> for the related error, | |||
NFS4ERR_RECLAIM_BAD. | NFS4ERR_RECLAIM_BAD. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="errors_pnfs" numbered="true" toc="default"> | ||||
<section title="pNFS Errors" anchor="errors_pnfs"> | <name>pNFS Errors</name> | |||
<t> | <t> | |||
This section deals with pNFS-related errors including those | This section deals with pNFS-related errors including those | |||
that are associated with using NFSv4.1 to communicate with a | that are associated with using NFSv4.1 to communicate with a | |||
data server. | data server. | |||
</t> | </t> | |||
<section title="NFS4ERR_BADIOMODE (Error Code 10049)" | <section anchor="err_BADIOMODE" numbered="true" toc="default"> | |||
anchor="err_BADIOMODE"> | <name>NFS4ERR_BADIOMODE (Error Code 10049)</name> | |||
<t> | <t> | |||
An invalid or inappropriate layout iomode was specified. | An invalid or inappropriate layout iomode was specified. | |||
For example an inappropriate layout iomode, suppose | For example an inappropriate layout iomode, suppose | |||
a client's LAYOUTGET operation specified an iomode of | a client's LAYOUTGET operation specified an iomode of | |||
LAYOUTIOMODE4_RW, and the server is neither able nor willing | LAYOUTIOMODE4_RW, and the server is neither able nor willing | |||
to let the client send write requests to data servers; the server | to let the client send write requests to data servers; the server | |||
can reply with NFS4ERR_BADIOMODE. The client would then | can reply with NFS4ERR_BADIOMODE. The client would then | |||
send another LAYOUTGET with an iomode of LAYOUTIOMODE4_READ. | send another LAYOUTGET with an iomode of LAYOUTIOMODE4_READ. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_BADLAYOUT (Error Code 10050)" | <section anchor="err_BADLAYOUT" numbered="true" toc="default"> | |||
anchor="err_BADLAYOUT"> | <name>NFS4ERR_BADLAYOUT (Error Code 10050)</name> | |||
<t> | <t> | |||
The layout specified is invalid in some way. For LAYOUTCOMMIT, | The layout specified is invalid in some way. For LAYOUTCOMMIT, | |||
this indicates that the specified layout is not held by the | this indicates that the specified layout is not held by the | |||
client or is not of mode LAYOUTIOMODE4_RW. For LAYOUTGET, | client or is not of mode LAYOUTIOMODE4_RW. For LAYOUTGET, | |||
it indicates that a layout matching the client's specification | it indicates that a layout matching the client's specification | |||
as to minimum length cannot be granted. | as to minimum length cannot be granted. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_LAYOUTTRYLATER (Error Code 10058)" | <section anchor="err_LAYOUTTRYLATER" numbered="true" toc="default"> | |||
anchor="err_LAYOUTTRYLATER"> | <name>NFS4ERR_LAYOUTTRYLATER (Error Code 10058)</name> | |||
<t> | <t> | |||
Layouts are temporarily unavailable for the file. The client | Layouts are temporarily unavailable for the file. The client | |||
should re-send later (but not with the same slot ID and | should re-send later (but not with the same slot ID and | |||
sequence ID; one or both MUST be different on the re-send). | sequence ID; one or both <bcp14>MUST</bcp14> be different on the re-send | |||
</t> | ). | |||
</section> | </t> | |||
<section title="NFS4ERR_LAYOUTUNAVAILABLE (Error Code 10059)" | </section> | |||
anchor="err_LAYOUTUNAVAILABLE"> | <section anchor="err_LAYOUTUNAVAILABLE" numbered="true" toc="default"> | |||
<t> | <name>NFS4ERR_LAYOUTUNAVAILABLE (Error Code 10059)</name> | |||
<t> | ||||
Returned when layouts are not available for the current file | Returned when layouts are not available for the current file | |||
system or the particular specified file. | system or the particular specified file. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_NOMATCHING_LAYOUT (Error Code 10060)" | <section anchor="err_NOMATCHING_LAYOUT" numbered="true" toc="default"> | |||
anchor="err_NOMATCHING_LAYOUT"> | <name>NFS4ERR_NOMATCHING_LAYOUT (Error Code 10060)</name> | |||
<t> | <t> | |||
Returned when layouts are recalled and the client has no layouts | Returned when layouts are recalled and the client has no layouts | |||
matching the specification of the layouts being recalled. | matching the specification of the layouts being recalled. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_PNFS_IO_HOLE (Error Code 10075)" | <section anchor="err_PNFS_IO_HOLE" numbered="true" toc="default"> | |||
anchor="err_PNFS_IO_HOLE"> | <name>NFS4ERR_PNFS_IO_HOLE (Error Code 10075)</name> | |||
<t> | <t> | |||
The pNFS client has attempted to read from or write to an | The pNFS client has attempted to read from or write to an | |||
illegal hole of a file of a data server that is using | illegal hole of a file of a data server that is using | |||
sparse packing. See <xref target="sparse_dense" />. | sparse packing. See <xref target="sparse_dense" format="default"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_PNFS_NO_LAYOUT (Error Code 10080)" | <section anchor="err_PNFS_NO_LAYOUT" numbered="true" toc="default"> | |||
anchor="err_PNFS_NO_LAYOUT"> | <name>NFS4ERR_PNFS_NO_LAYOUT (Error Code 10080)</name> | |||
<t> | <t> | |||
The pNFS client has attempted to read from or write to a file | The pNFS client has attempted to read from or write to a file | |||
(using a request to a data server) without holding a valid | (using a request to a data server) without holding a valid | |||
layout. This includes the case where the client had a layout, | layout. This includes the case where the client had a layout, | |||
but the iomode does not allow a WRITE. | but the iomode does not allow a WRITE. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_RETURNCONFLICT (Error Code 10086)" | <section anchor="err_RETURNCONFLICT" numbered="true" toc="default"> | |||
anchor="err_RETURNCONFLICT"> | <name>NFS4ERR_RETURNCONFLICT (Error Code 10086)</name> | |||
<t> | <t> | |||
A layout | A layout | |||
is unavailable due to an attempt to perform the LAYOUTGET | is unavailable due to an attempt to perform the LAYOUTGET | |||
before a pending LAYOUTRETURN on the file has been received. | before a pending LAYOUTRETURN on the file has been received. | |||
See <xref target="layout_server_consider" />. | See <xref target="layout_server_consider" format="default"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_UNKNOWN_LAYOUTTYPE (Error Code 10062)" | <section anchor="err_UNKNOWN_LAYOUTTYPE" numbered="true" toc="default" | |||
anchor="err_UNKNOWN_LAYOUTTYPE"> | > | |||
<t> | <name>NFS4ERR_UNKNOWN_LAYOUTTYPE (Error Code 10062)</name> | |||
<t> | ||||
The client has specified a layout type that is not supported by | The client has specified a layout type that is not supported by | |||
the server. | the server. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="errors_sess_use" numbered="true" toc="default"> | ||||
<section title="Session Use Errors" anchor="errors_sess_use"> | <name>Session Use Errors</name> | |||
<t> | <t> | |||
This section deals with errors encountered when using sessions, | This section deals with errors encountered when using sessions, | |||
that is, errors encountered when a request uses a Sequence | that is, errors encountered when a request uses a Sequence | |||
(i.e., either SEQUENCE or CB_SEQUENCE) operation. | (i.e., either SEQUENCE or CB_SEQUENCE) operation. | |||
</t> | </t> | |||
<section title="NFS4ERR_BADSESSION (Error Code 10052)" | <section anchor="err_BADSESSION" numbered="true" toc="default"> | |||
anchor="err_BADSESSION"> | <name>NFS4ERR_BADSESSION (Error Code 10052)</name> | |||
<t> | <t> | |||
The specified session ID is unknown to the server | The specified session ID is unknown to the server | |||
to which the operation is addressed. | to which the operation is addressed. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_BADSLOT (Error Code 10053)" | <section anchor="err_BADSLOT" numbered="true" toc="default"> | |||
anchor="err_BADSLOT"> | <name>NFS4ERR_BADSLOT (Error Code 10053)</name> | |||
<t> | <t> | |||
The requester sent a Sequence operation | The requester sent a Sequence operation | |||
that attempted to use a slot the replier | that attempted to use a slot the replier | |||
does not have in its slot table. It is possible the | does not have in its slot table. It is possible the | |||
slot may have been retired. | slot may have been retired. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_BAD_HIGH_SLOT (Error Code 10077)" | <section anchor="err_BAD_HIGH_SLOT" numbered="true" toc="default"> | |||
anchor="err_BAD_HIGH_SLOT"> | <name>NFS4ERR_BAD_HIGH_SLOT (Error Code 10077)</name> | |||
<t> | <t> | |||
The highest_slot argument in a Sequence operation | The highest_slot argument in a Sequence operation | |||
exceeds the replier's enforced highest_slotid. | exceeds the replier's enforced highest_slotid. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_CB_PATH_DOWN (Error Code 10048)" | <section anchor="err_CB_PATH_DOWN" numbered="true" toc="default"> | |||
anchor="err_CB_PATH_DOWN"> | <name>NFS4ERR_CB_PATH_DOWN (Error Code 10048)</name> | |||
<t> | <t> | |||
There is a problem contacting the client via | There is a problem contacting the client via | |||
the callback path. The function of this error has | the callback path. The function of this error has | |||
been mostly superseded by the use of | been mostly superseded by the use of | |||
status flags in the reply to the SEQUENCE | status flags in the reply to the SEQUENCE | |||
operation (see <xref target="OP_SEQUENCE" />). | operation (see <xref target="OP_SEQUENCE" format="default"/>). | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_DEADSESSION (Error Code 10078)" | <section anchor="err_DEADSESSION" numbered="true" toc="default"> | |||
anchor="err_DEADSESSION"> | <name>NFS4ERR_DEADSESSION (Error Code 10078)</name> | |||
<t> | <t> | |||
The specified session is a persistent session that is | The specified session is a persistent session that is | |||
dead and does not accept new | dead and does not accept new | |||
requests or perform new operations on existing requests | requests or perform new operations on existing requests | |||
(in the case in which a request was partially executed | (in the case in which a request was partially executed | |||
before server restart). | before server restart). | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_CONN_NOT_BOUND_TO_SESSION (Error Code 10055)" | <section anchor="err_CONN_NOT_BOUND_TO_SESSION" numbered="true" toc="d | |||
anchor="err_CONN_NOT_BOUND_TO_SESSION"> | efault"> | |||
<t> | <name>NFS4ERR_CONN_NOT_BOUND_TO_SESSION (Error Code 10055)</name> | |||
<t> | ||||
A Sequence operation was sent on a connection that has not | A Sequence operation was sent on a connection that has not | |||
been associated with the specified session, | been associated with the specified session, | |||
where the client specified that connection association | where the client specified that connection association | |||
was to be enforced with SP4_MACH_CRED or SP4_SSV state protection. | was to be enforced with SP4_MACH_CRED or SP4_SSV state protection. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_SEQ_FALSE_RETRY (Error Code 10076)" | <section anchor="err_SEQ_FALSE_RETRY" numbered="true" toc="default"> | |||
anchor="err_SEQ_FALSE_RETRY"> | <name>NFS4ERR_SEQ_FALSE_RETRY (Error Code 10076)</name> | |||
<t> | <t> | |||
The requester sent a Sequence operation with a | The requester sent a Sequence operation with a | |||
slot ID and sequence ID that are in the reply cache, but | slot ID and sequence ID that are in the reply cache, but | |||
the replier has detected that the retried request | the replier has detected that the retried request | |||
is not the same as the original request. | is not the same as the original request. | |||
See <xref target="false_retry"/>. | See <xref target="false_retry" format="default"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_SEQ_MISORDERED (Error Code 10063)" | <section anchor="err_SEQ_MISORDERED" numbered="true" toc="default"> | |||
anchor="err_SEQ_MISORDERED"> | <name>NFS4ERR_SEQ_MISORDERED (Error Code 10063)</name> | |||
<t> | <t> | |||
The requester sent a Sequence operation | The requester sent a Sequence operation | |||
with an invalid sequence ID. | with an invalid sequence ID. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="errors_sess_mgt" numbered="true" toc="default"> | ||||
<section title="Session Management Errors" anchor="errors_sess_mgt"> | <name>Session Management Errors</name> | |||
<t> | <t> | |||
This section deals with errors associated with requests used | This section deals with errors associated with requests used | |||
in session management. | in session management. | |||
</t> | </t> | |||
<section title="NFS4ERR_BACK_CHAN_BUSY (Error Code 10057)" | <section anchor="err_BACK_CHAN_BUSY" numbered="true" toc="default"> | |||
anchor="err_BACK_CHAN_BUSY"> | <name>NFS4ERR_BACK_CHAN_BUSY (Error Code 10057)</name> | |||
<t> | <t> | |||
An attempt was made to destroy a session when the session | An attempt was made to destroy a session when the session | |||
cannot be destroyed because the server has | cannot be destroyed because the server has | |||
callback requests outstanding. | callback requests outstanding. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_BAD_SESSION_DIGEST (Error Code 10051)" | <section anchor="err_BAD_SESSION_DIGEST" numbered="true" toc="default" | |||
anchor="err_BAD_SESSION_DIGEST"> | > | |||
<t> | <name>NFS4ERR_BAD_SESSION_DIGEST (Error Code 10051)</name> | |||
<t> | ||||
The digest used in a SET_SSV request is not valid. | The digest used in a SET_SSV request is not valid. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="errors_client_mgt" numbered="true" toc="default"> | ||||
<section title="Client Management Errors" anchor="errors_client_mgt"> | <name>Client Management Errors</name> | |||
<t> | <t> | |||
This section deals with errors associated with requests used | This section deals with errors associated with requests used | |||
to create and manage client IDs. | to create and manage client IDs. | |||
</t> | </t> | |||
<section title="NFS4ERR_CLIENTID_BUSY (Error Code 10074)" | <section anchor="err_CLIENTID_BUSY" numbered="true" toc="default"> | |||
anchor="err_CLIENTID_BUSY"> | <name>NFS4ERR_CLIENTID_BUSY (Error Code 10074)</name> | |||
<t> | <t> | |||
The DESTROY_CLIENTID operation has found there are | The DESTROY_CLIENTID operation has found there are | |||
sessions and/or unexpired state associated with the | sessions and/or unexpired state associated with the | |||
client ID to be destroyed. | client ID to be destroyed. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_CLID_INUSE (Error Code 10017)" | <section anchor="err_CLID_INUSE" numbered="true" toc="default"> | |||
anchor="err_CLID_INUSE"> | <name>NFS4ERR_CLID_INUSE (Error Code 10017)</name> | |||
<t> | <t> | |||
While processing an EXCHANGE_ID operation, the server was presented | While processing an EXCHANGE_ID operation, the server was presented | |||
with a co_ownerid field that matches an existing client with | with a co_ownerid field that matches an existing client with | |||
valid leased state, but the principal sending the EXCHANGE_ID | valid leased state, but the principal sending the EXCHANGE_ID | |||
operation differs from the principal that established the existing | operation differs from the principal that established the existing | |||
client. | client. | |||
This indicates a collision (most likely due to chance) between | This indicates a collision (most likely due to chance) between | |||
clients. The client should recover by changing the | clients. The client should recover by changing the | |||
co_ownerid and re-sending EXCHANGE_ID (but not with the same slot ID and | co_ownerid and re-sending EXCHANGE_ID (but not with the same slot ID and | |||
sequence ID; one or both MUST be different on the re-send). | sequence ID; one or both <bcp14>MUST</bcp14> be different on the re-send | |||
</t> | ). | |||
</section> | </t> | |||
<section title="NFS4ERR_ENCR_ALG_UNSUPP (Error Code 10079)" | </section> | |||
anchor="err_ENCR_ALG_UNSUPP"> | <section anchor="err_ENCR_ALG_UNSUPP" numbered="true" toc="default"> | |||
<t> | <name>NFS4ERR_ENCR_ALG_UNSUPP (Error Code 10079)</name> | |||
<t> | ||||
An EXCHANGE_ID was sent that specified state protection | An EXCHANGE_ID was sent that specified state protection | |||
via SSV, and where the set of encryption algorithms presented | via SSV, and where the set of encryption algorithms presented | |||
by the client did not include any supported by the server. | by the client did not include any supported by the server. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_HASH_ALG_UNSUPP (Error Code 10072)" | <section anchor="err_HASH_ALG_UNSUPP" numbered="true" toc="default"> | |||
anchor="err_HASH_ALG_UNSUPP"> | <name>NFS4ERR_HASH_ALG_UNSUPP (Error Code 10072)</name> | |||
<t> | <t> | |||
An EXCHANGE_ID was sent that specified state protection | An EXCHANGE_ID was sent that specified state protection | |||
via SSV, and where the set of hashing algorithms presented | via SSV, and where the set of hashing algorithms presented | |||
by the client did not include any supported by the server. | by the client did not include any supported by the server. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_STALE_CLIENTID (Error Code 10022)" | <section anchor="err_STALE_CLIENTID" numbered="true" toc="default"> | |||
anchor="err_STALE_CLIENTID"> | <name>NFS4ERR_STALE_CLIENTID (Error Code 10022)</name> | |||
<t> | <t> | |||
A client ID not recognized by the server was passed to an | A client ID not recognized by the server was passed to an | |||
operation. Note that unlike the case of NFSv4.0, client IDs | operation. Note that unlike the case of NFSv4.0, client IDs | |||
are not passed explicitly to the server in ordinary locking | are not passed explicitly to the server in ordinary locking | |||
operations and cannot result in this error. Instead, when | operations and cannot result in this error. Instead, when | |||
there is a server restart, it is first manifested through | there is a server restart, it is first manifested through | |||
an error on the associated session, and the staleness of the | an error on the associated session, and the staleness of the | |||
client ID is detected when trying to associate a client ID | client ID is detected when trying to associate a client ID | |||
with a new session. | with a new session. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="errors_deleg" numbered="true" toc="default"> | ||||
<section title="Delegation Errors" anchor="errors_deleg"> | <name>Delegation Errors</name> | |||
<t> | <t> | |||
This section deals with errors associated with requesting and | This section deals with errors associated with requesting and | |||
returning delegations. | returning delegations. | |||
</t> | </t> | |||
<section title="NFS4ERR_DELEG_ALREADY_WANTED (Error Code 10056)" | <section anchor="err_DELEG_ALREADY_WANTED" numbered="true" toc="defaul | |||
anchor="err_DELEG_ALREADY_WANTED"> | t"> | |||
<t> | <name>NFS4ERR_DELEG_ALREADY_WANTED (Error Code 10056)</name> | |||
<t> | ||||
The client has requested a delegation when it had already | The client has requested a delegation when it had already | |||
registered that it wants that same delegation. | registered that it wants that same delegation. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_DIRDELEG_UNAVAIL (Error Code 10084)" | <section anchor="err_DIRDELEG_UNAVAIL" numbered="true" toc="default"> | |||
anchor="err_DIRDELEG_UNAVAIL"> | <name>NFS4ERR_DIRDELEG_UNAVAIL (Error Code 10084)</name> | |||
<t> | <t> | |||
This error is returned when the server is unable or unwilling | This error is returned when the server is unable or unwilling | |||
to provide a requested directory delegation. | to provide a requested directory delegation. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_RECALLCONFLICT (Error Code 10061)" | <section anchor="err_RECALLCONFLICT" numbered="true" toc="default"> | |||
anchor="err_RECALLCONFLICT"> | <name>NFS4ERR_RECALLCONFLICT (Error Code 10061)</name> | |||
<t> | <t> | |||
A recallable object (i.e., a layout or delegation) | A recallable object (i.e., a layout or delegation) | |||
is unavailable due to a conflicting recall operation that is | is unavailable due to a conflicting recall operation that is | |||
currently in progress for that object. | currently in progress for that object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_REJECT_DELEG (Error Code 10085)" | <section anchor="err_REJECT_DELEG" numbered="true" toc="default"> | |||
anchor="err_REJECT_DELEG"> | <name>NFS4ERR_REJECT_DELEG (Error Code 10085)</name> | |||
<t> | <t> | |||
The callback operation invoked to deal with a new delegation has | The callback operation invoked to deal with a new delegation has | |||
rejected it. | rejected it. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="errors_attr" numbered="true" toc="default"> | ||||
<section title="Attribute Handling Errors" anchor="errors_attr"> | <name>Attribute Handling Errors</name> | |||
<t> | <t> | |||
This section deals with errors specific to attribute handling | This section deals with errors specific to attribute handling | |||
within NFSv4. | within NFSv4. | |||
</t> | </t> | |||
<section title="NFS4ERR_ATTRNOTSUPP (Error Code 10032)" | <section anchor="err_ATTRNOTSUPP" numbered="true" toc="default"> | |||
anchor="err_ATTRNOTSUPP"> | <name>NFS4ERR_ATTRNOTSUPP (Error Code 10032)</name> | |||
<t> | <t> | |||
An attribute specified is not supported by the server. This | An attribute specified is not supported by the server. This | |||
error MUST NOT be returned by the GETATTR operation. | error <bcp14>MUST NOT</bcp14> be returned by the GETATTR operation. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_BADOWNER (Error Code 10039)" | <section anchor="err_BADOWNER" numbered="true" toc="default"> | |||
anchor="err_BADOWNER"> | <name>NFS4ERR_BADOWNER (Error Code 10039)</name> | |||
<t> | <t> | |||
This error is returned when an owner or owner_group attribute value or t he who | This error is returned when an owner or owner_group attribute value or t he who | |||
field of an ACE within an ACL attribute value cannot be | field of an ACE within an ACL attribute value cannot be | |||
translated to a local representation. | translated to a local representation. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_NOT_SAME (Error Code 10027)" | <section anchor="err_NOT_SAME" numbered="true" toc="default"> | |||
anchor="err_NOT_SAME"> | <name>NFS4ERR_NOT_SAME (Error Code 10027)</name> | |||
<t> | <t> | |||
This error is returned by the VERIFY operation to signify | This error is returned by the VERIFY operation to signify | |||
that the attributes compared were not the same as those provided | that the attributes compared were not the same as those provided | |||
in the client's request. | in the client's request. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_SAME (Error Code 10009)" | <section anchor="err_SAME" numbered="true" toc="default"> | |||
anchor="err_SAME"> | <name>NFS4ERR_SAME (Error Code 10009)</name> | |||
<t> | <t> | |||
This error is returned by the NVERIFY operation to signify | This error is returned by the NVERIFY operation to signify | |||
that the attributes compared were the same as those provided | that the attributes compared were the same as those provided | |||
in the client's request. | in the client's request. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<section anchor="errors_obs" numbered="true" toc="default"> | ||||
<section title="Obsoleted Errors" anchor="errors_obs"> | <name>Obsoleted Errors</name> | |||
<t> | <t> | |||
These errors MUST NOT be generated by any NFSv4.1 operation. | These errors <bcp14>MUST NOT</bcp14> be generated by any NFSv4.1 operation | |||
. | ||||
This can be for a number of reasons. | This can be for a number of reasons. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The function provided by the error has been superseded | The function provided by the error has been superseded | |||
by one of the status bits returned by the SEQUENCE | by one of the status bits returned by the SEQUENCE | |||
operation. | operation. | |||
</t> | </li> | |||
<t> | <li> | |||
The new session structure and associated change in | The new session structure and associated change in | |||
locking have made the error unnecessary. | locking have made the error unnecessary. | |||
</t> | </li> | |||
<t> | <li> | |||
There has been a restructuring of some errors for | There has been a restructuring of some errors for | |||
NFSv4.1 that resulted in the elimination of certain errors. | NFSv4.1 that resulted in the elimination of certain errors. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <section anchor="err_BAD_SEQID" numbered="true" toc="default"> | |||
<section title="NFS4ERR_BAD_SEQID (Error Code 10026)" | <name>NFS4ERR_BAD_SEQID (Error Code 10026)</name> | |||
anchor="err_BAD_SEQID"> | <t> | |||
<t> | ||||
The sequence number (seqid) in a locking request is neither the | The sequence number (seqid) in a locking request is neither the | |||
next expected number or the last number processed. These | next expected number or the last number processed. These | |||
seqids are ignored in NFSv4.1. | seqids are ignored in NFSv4.1. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_LEASE_MOVED (Error Code 10031)" | <section anchor="err_LEASE_MOVED" numbered="true" toc="default"> | |||
anchor="err_LEASE_MOVED"> | <name>NFS4ERR_LEASE_MOVED (Error Code 10031)</name> | |||
<t> | <t> | |||
A lease being renewed is associated with a file system | A lease being renewed is associated with a file system | |||
that has been migrated to a new server. The error has | that has been migrated to a new server. The error has | |||
been superseded by the SEQ4_STATUS_LEASE_MOVED status bit | been superseded by the SEQ4_STATUS_LEASE_MOVED status bit | |||
(see <xref target="OP_SEQUENCE" />). | (see <xref target="OP_SEQUENCE" format="default"/>). | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_NXIO (Error Code 5)" | <section anchor="err_NXIO" numbered="true" toc="default"> | |||
anchor="err_NXIO"> | <name>NFS4ERR_NXIO (Error Code 5)</name> | |||
<t> | <t> | |||
I/O error. No such device or address. This error is | I/O error. No such device or address. This error is | |||
for errors involving block and character device access, | for errors involving block and character device access, | |||
but because NFSv4.1 is not a device-access protocol, this | but because NFSv4.1 is not a device-access protocol, this | |||
error is not applicable. | error is not applicable. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_RESTOREFH (Error Code 10030)" | <section anchor="err_RESTOREFH" numbered="true" toc="default"> | |||
anchor="err_RESTOREFH"> | <name>NFS4ERR_RESTOREFH (Error Code 10030)</name> | |||
<t> | <t> | |||
The RESTOREFH operation does not have a saved filehandle | The RESTOREFH operation does not have a saved filehandle | |||
(identified by SAVEFH) to operate upon. In NFSv4.1, this error has | (identified by SAVEFH) to operate upon. In NFSv4.1, this error has | |||
been superseded by NFS4ERR_NOFILEHANDLE. | been superseded by NFS4ERR_NOFILEHANDLE. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="NFS4ERR_STALE_STATEID (Error Code 10023)" | <section anchor="err_STALE_STATEID" numbered="true" toc="default"> | |||
anchor="err_STALE_STATEID"> | <name>NFS4ERR_STALE_STATEID (Error Code 10023)</name> | |||
<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 MUST 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> | ||||
<!-- When adding new errors above, add them to the next section under --> | ||||
<!-- the appropriate operation; the next table for errors to --> | ||||
<!-- operations is automatically generated. --> | ||||
<section title="Operations and Their Valid Errors"> | <section numbered="true" toc="default"> | |||
<t> | <name>Operations and Their Valid Errors</name> | |||
<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: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
The operations that MUST NOT be implemented: | <li> | |||
The operations that <bcp14>MUST NOT</bcp14> be implemented: | ||||
OPEN_CONFIRM, RELEASE_LOCKOWNER, RENEW, SETCLIENTID, and | OPEN_CONFIRM, RELEASE_LOCKOWNER, RENEW, SETCLIENTID, and | |||
SETCLIENTID_CONFIRM. | SETCLIENTID_CONFIRM. | |||
</t> | </li> | |||
<t> | <li> | |||
The invalid operation: ILLEGAL. | The invalid operation: ILLEGAL. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <table anchor="op_error_returns" align="center"> | |||
<texttable anchor='op_error_returns'> | <name>Valid Error Returns for Each Protocol Operation</name> | |||
<preamble> Valid Error Returns for Each Protocol | <thead> | |||
Operation </preamble> | <tr> | |||
<th align="left">Operation</th> | ||||
<ttcol align='left'>Operation</ttcol> | <th align="left">Errors</th> | |||
<ttcol align='left'>Errors</ttcol> | </tr> | |||
<!-- DO NOT MOVE THIS OR THE NEXT LINE - IT MUST BE AT THE START OF TABLE --> | </thead> | |||
<!-- STARTOFTHEERRORTABLE --> | <tbody> | |||
<tr> | ||||
<c>ACCESS</c> | <td align="left">ACCESS</td> | |||
<c> | <td align="left"> | |||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_IO, | NFS4ERR_IO, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS | NFS4ERR_TOO_MANY_OPS | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>BACKCHANNEL_CTL</c> | <tr> | |||
<c> | <td align="left">BACKCHANNEL_CTL</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_NOENT, | NFS4ERR_NOENT, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_TOO_MANY_OPS | NFS4ERR_TOO_MANY_OPS | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>BIND_CONN_TO_SESSION</c> | <tr> | |||
<c> | <td align="left">BIND_CONN_TO_SESSION</td> | |||
<td align="left"> | ||||
NFS4ERR_BADSESSION, | NFS4ERR_BADSESSION, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_SESSION_DIGEST, | NFS4ERR_BAD_SESSION_DIGEST, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_NOT_ONLY_OP, | NFS4ERR_NOT_ONLY_OP, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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 | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CLOSE</c> | <tr> | |||
<c> | <td align="left">CLOSE</td> | |||
<td align="left"> | ||||
NFS4ERR_ADMIN_REVOKED, | NFS4ERR_ADMIN_REVOKED, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_EXPIRED, | NFS4ERR_EXPIRED, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_LOCKS_HELD, | NFS4ERR_LOCKS_HELD, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
NFS4ERR_OLD_STATEID, | NFS4ERR_OLD_STATEID, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_CRED | NFS4ERR_WRONG_CRED | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>COMMIT</c> | <tr> | |||
<c> | <td align="left">COMMIT</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_IO, | NFS4ERR_IO, | |||
NFS4ERR_ISDIR, | NFS4ERR_ISDIR, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_SYMLINK, | NFS4ERR_SYMLINK, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CREATE</c> | <tr> | |||
<c> | <td align="left">CREATE</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_ATTRNOTSUPP, | NFS4ERR_ATTRNOTSUPP, | |||
NFS4ERR_BADCHAR, | NFS4ERR_BADCHAR, | |||
NFS4ERR_BADNAME, | NFS4ERR_BADNAME, | |||
NFS4ERR_BADOWNER, | NFS4ERR_BADOWNER, | |||
NFS4ERR_BADTYPE, | NFS4ERR_BADTYPE, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DQUOT, | NFS4ERR_DQUOT, | |||
skipping to change at line 25187 ¶ | skipping to change at line 25569 ¶ | |||
NFS4ERR_PERM, | NFS4ERR_PERM, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_ROFS, | NFS4ERR_ROFS, | |||
NFS4ERR_SERVERFAULT, | NFS4ERR_SERVERFAULT, | |||
NFS4ERR_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_UNSAFE_COMPOUND | NFS4ERR_UNSAFE_COMPOUND | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CREATE_SESSION</c> | <tr> | |||
<c> | <td align="left">CREATE_SESSION</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_CLID_INUSE, | NFS4ERR_CLID_INUSE, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_NOENT, | NFS4ERR_NOENT, | |||
NFS4ERR_NOT_ONLY_OP, | NFS4ERR_NOT_ONLY_OP, | |||
NFS4ERR_NOSPC, | NFS4ERR_NOSPC, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_SEQ_MISORDERED, | NFS4ERR_SEQ_MISORDERED, | |||
NFS4ERR_SERVERFAULT, | NFS4ERR_SERVERFAULT, | |||
NFS4ERR_STALE_CLIENTID, | NFS4ERR_STALE_CLIENTID, | |||
NFS4ERR_TOOSMALL, | NFS4ERR_TOOSMALL, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_CRED | NFS4ERR_WRONG_CRED | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>DELEGPURGE</c> | <tr> | |||
<c> | <td align="left">DELEGPURGE</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_NOTSUPP, | NFS4ERR_NOTSUPP, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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, | |||
NFS4ERR_WRONG_CRED | NFS4ERR_WRONG_CRED | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>DELEGRETURN</c> | <tr> | |||
<c> | <td align="left">DELEGRETURN</td> | |||
<td align="left"> | ||||
NFS4ERR_ADMIN_REVOKED, | NFS4ERR_ADMIN_REVOKED, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DELEG_REVOKED, | NFS4ERR_DELEG_REVOKED, | |||
NFS4ERR_EXPIRED, | NFS4ERR_EXPIRED, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
skipping to change at line 25260 ¶ | skipping to change at line 25639 ¶ | |||
NFS4ERR_OLD_STATEID, | NFS4ERR_OLD_STATEID, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_CRED | NFS4ERR_WRONG_CRED | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>DESTROY_CLIENTID</c> | <tr> | |||
<c> | <td align="left">DESTROY_CLIENTID</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_CLIENTID_BUSY, | NFS4ERR_CLIENTID_BUSY, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_NOT_ONLY_OP, | NFS4ERR_NOT_ONLY_OP, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE_CLIENTID, | NFS4ERR_STALE_CLIENTID, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_CRED | NFS4ERR_WRONG_CRED | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>DESTROY_SESSION</c> | <tr> | |||
<c> | <td align="left">DESTROY_SESSION</td> | |||
<td align="left"> | ||||
NFS4ERR_BACK_CHAN_BUSY, | NFS4ERR_BACK_CHAN_BUSY, | |||
NFS4ERR_BADSESSION, | NFS4ERR_BADSESSION, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_CB_PATH_DOWN, | NFS4ERR_CB_PATH_DOWN, | |||
NFS4ERR_CONN_NOT_BOUND_TO_SESSION, | NFS4ERR_CONN_NOT_BOUND_TO_SESSION, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_NOT_ONLY_OP, | NFS4ERR_NOT_ONLY_OP, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE_CLIENTID, | NFS4ERR_STALE_CLIENTID, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_CRED | NFS4ERR_WRONG_CRED | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>EXCHANGE_ID</c> | <tr> | |||
<c> | <td align="left">EXCHANGE_ID</td> | |||
<td align="left"> | ||||
NFS4ERR_BADCHAR, | NFS4ERR_BADCHAR, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_CLID_INUSE, | NFS4ERR_CLID_INUSE, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_ENCR_ALG_UNSUPP, | NFS4ERR_ENCR_ALG_UNSUPP, | |||
NFS4ERR_HASH_ALG_UNSUPP, | NFS4ERR_HASH_ALG_UNSUPP, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_NOENT, | NFS4ERR_NOENT, | |||
NFS4ERR_NOT_ONLY_OP, | NFS4ERR_NOT_ONLY_OP, | |||
NFS4ERR_NOT_SAME, | NFS4ERR_NOT_SAME, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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 | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>FREE_STATEID</c> | <tr> | |||
<c> | <td align="left">FREE_STATEID</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_LOCKS_HELD, | NFS4ERR_LOCKS_HELD, | |||
NFS4ERR_OLD_STATEID, | NFS4ERR_OLD_STATEID, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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, | |||
NFS4ERR_WRONG_CRED | NFS4ERR_WRONG_CRED | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>GET_DIR_DELEGATION</c> | <tr> | |||
<c> | <td align="left">GET_DIR_DELEGATION</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DIRDELEG_UNAVAIL, | NFS4ERR_DIRDELEG_UNAVAIL, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_GRACE, | NFS4ERR_GRACE, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_IO, | NFS4ERR_IO, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
skipping to change at line 25376 ¶ | skipping to change at line 25750 ¶ | |||
NFS4ERR_NOTDIR, | NFS4ERR_NOTDIR, | |||
NFS4ERR_NOTSUPP, | NFS4ERR_NOTSUPP, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS | NFS4ERR_TOO_MANY_OPS | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>GETATTR</c> | <tr> | |||
<c> | <td align="left">GETATTR</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_GRACE, | NFS4ERR_GRACE, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_IO, | NFS4ERR_IO, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>GETDEVICEINFO</c> | <tr> | |||
<c> | <td align="left">GETDEVICEINFO</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_NOENT, | NFS4ERR_NOENT, | |||
NFS4ERR_NOTSUPP, | NFS4ERR_NOTSUPP, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_TOOSMALL, | NFS4ERR_TOOSMALL, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_UNKNOWN_LAYOUTTYPE | NFS4ERR_UNKNOWN_LAYOUTTYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>GETDEVICELIST</c> | <tr> | |||
<c> | <td align="left">GETDEVICELIST</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_COOKIE, | NFS4ERR_BAD_COOKIE, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_IO, | NFS4ERR_IO, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
NFS4ERR_NOTSUPP, | NFS4ERR_NOTSUPP, | |||
NFS4ERR_NOT_SAME, | NFS4ERR_NOT_SAME, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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, | |||
NFS4ERR_UNKNOWN_LAYOUTTYPE | NFS4ERR_UNKNOWN_LAYOUTTYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>GETFH</c> | <tr> | |||
<c> | <td align="left">GETFH</td> | |||
<td align="left"> | ||||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_STALE | NFS4ERR_STALE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>ILLEGAL</c> | <tr> | |||
<c> | <td align="left">ILLEGAL</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_OP_ILLEGAL | NFS4ERR_OP_ILLEGAL | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>LAYOUTCOMMIT</c> | <tr> | |||
<c> | <td align="left">LAYOUTCOMMIT</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_ADMIN_REVOKED, | NFS4ERR_ADMIN_REVOKED, | |||
NFS4ERR_ATTRNOTSUPP, | NFS4ERR_ATTRNOTSUPP, | |||
NFS4ERR_BADIOMODE, | NFS4ERR_BADIOMODE, | |||
NFS4ERR_BADLAYOUT, | NFS4ERR_BADLAYOUT, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DELEG_REVOKED, | NFS4ERR_DELEG_REVOKED, | |||
NFS4ERR_EXPIRED, | NFS4ERR_EXPIRED, | |||
skipping to change at line 25510 ¶ | skipping to change at line 25878 ¶ | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_SYMLINK, | NFS4ERR_SYMLINK, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_UNKNOWN_LAYOUTTYPE, | NFS4ERR_UNKNOWN_LAYOUTTYPE, | |||
NFS4ERR_WRONG_CRED | NFS4ERR_WRONG_CRED | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>LAYOUTGET</c> | <tr> | |||
<c> | <td align="left">LAYOUTGET</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_ADMIN_REVOKED, | NFS4ERR_ADMIN_REVOKED, | |||
NFS4ERR_BADIOMODE, | NFS4ERR_BADIOMODE, | |||
NFS4ERR_BADLAYOUT, | NFS4ERR_BADLAYOUT, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DELEG_REVOKED, | NFS4ERR_DELEG_REVOKED, | |||
NFS4ERR_DQUOT, | NFS4ERR_DQUOT, | |||
skipping to change at line 25552 ¶ | skipping to change at line 25919 ¶ | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOOSMALL, | NFS4ERR_TOOSMALL, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_UNKNOWN_LAYOUTTYPE, | NFS4ERR_UNKNOWN_LAYOUTTYPE, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>LAYOUTRETURN</c> | <tr> | |||
<c> | <td align="left">LAYOUTRETURN</td> | |||
<td align="left"> | ||||
NFS4ERR_ADMIN_REVOKED, | NFS4ERR_ADMIN_REVOKED, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DELEG_REVOKED, | NFS4ERR_DELEG_REVOKED, | |||
NFS4ERR_EXPIRED, | NFS4ERR_EXPIRED, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_GRACE, | NFS4ERR_GRACE, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
skipping to change at line 25586 ¶ | skipping to change at line 25952 ¶ | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_UNKNOWN_LAYOUTTYPE, | NFS4ERR_UNKNOWN_LAYOUTTYPE, | |||
NFS4ERR_WRONG_CRED, | NFS4ERR_WRONG_CRED, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>LINK</c> | <tr> | |||
<c> | <td align="left">LINK</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_BADCHAR, | NFS4ERR_BADCHAR, | |||
NFS4ERR_BADNAME, | NFS4ERR_BADNAME, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DQUOT, | NFS4ERR_DQUOT, | |||
NFS4ERR_EXIST, | NFS4ERR_EXIST, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_FILE_OPEN, | NFS4ERR_FILE_OPEN, | |||
skipping to change at line 25627 ¶ | skipping to change at line 25992 ¶ | |||
NFS4ERR_REQ_TOO_BIG, | NFS4ERR_REQ_TOO_BIG, | |||
NFS4ERR_RETRY_UNCACHED_REP, | NFS4ERR_RETRY_UNCACHED_REP, | |||
NFS4ERR_ROFS, | NFS4ERR_ROFS, | |||
NFS4ERR_SERVERFAULT, | NFS4ERR_SERVERFAULT, | |||
NFS4ERR_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_SYMLINK, | NFS4ERR_SYMLINK, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONGSEC, | NFS4ERR_WRONGSEC, | |||
NFS4ERR_WRONG_TYPE, | NFS4ERR_WRONG_TYPE, | |||
NFS4ERR_XDEV | NFS4ERR_XDEV | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>LOCK</c> | <tr> | |||
<c> | <td align="left">LOCK</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_ADMIN_REVOKED, | NFS4ERR_ADMIN_REVOKED, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_RANGE, | NFS4ERR_BAD_RANGE, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DEADLOCK, | NFS4ERR_DEADLOCK, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DENIED, | NFS4ERR_DENIED, | |||
NFS4ERR_EXPIRED, | NFS4ERR_EXPIRED, | |||
skipping to change at line 25669 ¶ | skipping to change at line 26033 ¶ | |||
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_ROFS, | NFS4ERR_ROFS, | |||
NFS4ERR_SERVERFAULT, | NFS4ERR_SERVERFAULT, | |||
NFS4ERR_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_SYMLINK, | NFS4ERR_SYMLINK, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_CRED, | NFS4ERR_WRONG_CRED, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>LOCKT</c> | <tr> | |||
<c> | <td align="left">LOCKT</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_RANGE, | NFS4ERR_BAD_RANGE, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DENIED, | NFS4ERR_DENIED, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_GRACE, | NFS4ERR_GRACE, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_ISDIR, | NFS4ERR_ISDIR, | |||
skipping to change at line 25700 ¶ | skipping to change at line 26063 ¶ | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_ROFS, | NFS4ERR_ROFS, | |||
NFS4ERR_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_SYMLINK, | NFS4ERR_SYMLINK, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_CRED, | NFS4ERR_WRONG_CRED, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>LOCKU</c> | <tr> | |||
<c> | <td align="left">LOCKU</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_ADMIN_REVOKED, | NFS4ERR_ADMIN_REVOKED, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_RANGE, | NFS4ERR_BAD_RANGE, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_EXPIRED, | NFS4ERR_EXPIRED, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
skipping to change at line 25730 ¶ | skipping to change at line 26092 ¶ | |||
NFS4ERR_OLD_STATEID, | NFS4ERR_OLD_STATEID, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_CRED | NFS4ERR_WRONG_CRED | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>LOOKUP</c> | <tr> | |||
<c> | <td align="left">LOOKUP</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_BADCHAR, | NFS4ERR_BADCHAR, | |||
NFS4ERR_BADNAME, | NFS4ERR_BADNAME, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_IO, | NFS4ERR_IO, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
skipping to change at line 25761 ¶ | skipping to change at line 26122 ¶ | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_SYMLINK, | NFS4ERR_SYMLINK, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONGSEC | NFS4ERR_WRONGSEC | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>LOOKUPP</c> | <tr> | |||
<c> | <td align="left">LOOKUPP</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_IO, | NFS4ERR_IO, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOENT, | NFS4ERR_NOENT, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
NFS4ERR_NOTDIR, | NFS4ERR_NOTDIR, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_SYMLINK, | NFS4ERR_SYMLINK, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONGSEC | NFS4ERR_WRONGSEC | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>NVERIFY</c> | <tr> | |||
<c> | <td align="left">NVERIFY</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_ATTRNOTSUPP, | NFS4ERR_ATTRNOTSUPP, | |||
NFS4ERR_BADCHAR, | NFS4ERR_BADCHAR, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_GRACE, | NFS4ERR_GRACE, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_IO, | NFS4ERR_IO, | |||
skipping to change at line 25817 ¶ | skipping to change at line 26176 ¶ | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_SAME, | NFS4ERR_SAME, | |||
NFS4ERR_SERVERFAULT, | NFS4ERR_SERVERFAULT, | |||
NFS4ERR_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_UNKNOWN_LAYOUTTYPE, | NFS4ERR_UNKNOWN_LAYOUTTYPE, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>OPEN</c> | <tr> | |||
<c> | <td align="left">OPEN</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_ADMIN_REVOKED, | NFS4ERR_ADMIN_REVOKED, | |||
NFS4ERR_ATTRNOTSUPP, | NFS4ERR_ATTRNOTSUPP, | |||
NFS4ERR_BADCHAR, | NFS4ERR_BADCHAR, | |||
NFS4ERR_BADNAME, | NFS4ERR_BADNAME, | |||
NFS4ERR_BADOWNER, | NFS4ERR_BADOWNER, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
skipping to change at line 25870 ¶ | skipping to change at line 26228 ¶ | |||
NFS4ERR_RETRY_UNCACHED_REP, | NFS4ERR_RETRY_UNCACHED_REP, | |||
NFS4ERR_ROFS, | NFS4ERR_ROFS, | |||
NFS4ERR_SERVERFAULT, | NFS4ERR_SERVERFAULT, | |||
NFS4ERR_SHARE_DENIED, | NFS4ERR_SHARE_DENIED, | |||
NFS4ERR_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_SYMLINK, | NFS4ERR_SYMLINK, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_UNSAFE_COMPOUND, | NFS4ERR_UNSAFE_COMPOUND, | |||
NFS4ERR_WRONGSEC, | NFS4ERR_WRONGSEC, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>OPEN_CONFIRM</c> | <tr> | |||
<c> | <td align="left">OPEN_CONFIRM</td> | |||
<td align="left"> | ||||
NFS4ERR_NOTSUPP | NFS4ERR_NOTSUPP | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>OPEN_DOWNGRADE</c> | <tr> | |||
<c> | <td align="left">OPEN_DOWNGRADE</td> | |||
<td align="left"> | ||||
NFS4ERR_ADMIN_REVOKED, | NFS4ERR_ADMIN_REVOKED, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_EXPIRED, | NFS4ERR_EXPIRED, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
skipping to change at line 25906 ¶ | skipping to change at line 26262 ¶ | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_ROFS, | NFS4ERR_ROFS, | |||
NFS4ERR_SERVERFAULT, | NFS4ERR_SERVERFAULT, | |||
NFS4ERR_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_CRED | NFS4ERR_WRONG_CRED | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>OPENATTR</c> | <tr> | |||
<c> | <td align="left">OPENATTR</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DQUOT, | NFS4ERR_DQUOT, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_IO, | NFS4ERR_IO, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOENT, | NFS4ERR_NOENT, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
skipping to change at line 25936 ¶ | skipping to change at line 26291 ¶ | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_ROFS, | NFS4ERR_ROFS, | |||
NFS4ERR_SERVERFAULT, | NFS4ERR_SERVERFAULT, | |||
NFS4ERR_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_UNSAFE_COMPOUND, | NFS4ERR_UNSAFE_COMPOUND, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>PUTFH</c> | <tr> | |||
<c> | <td align="left">PUTFH</td> | |||
<td align="left"> | ||||
NFS4ERR_BADHANDLE, | NFS4ERR_BADHANDLE, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONGSEC | NFS4ERR_WRONGSEC | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>PUTPUBFH</c> | <tr> | |||
<c> | <td align="left">PUTPUBFH</td> | |||
<td align="left"> | ||||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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, | |||
NFS4ERR_WRONGSEC | NFS4ERR_WRONGSEC | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>PUTROOTFH</c> | <tr> | |||
<c> | <td align="left">PUTROOTFH</td> | |||
<td align="left"> | ||||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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, | |||
NFS4ERR_WRONGSEC | NFS4ERR_WRONGSEC | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>READ</c> | <tr> | |||
<c> | <td align="left">READ</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_ADMIN_REVOKED, | NFS4ERR_ADMIN_REVOKED, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DELEG_REVOKED, | NFS4ERR_DELEG_REVOKED, | |||
NFS4ERR_EXPIRED, | NFS4ERR_EXPIRED, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_GRACE, | NFS4ERR_GRACE, | |||
skipping to change at line 26028 ¶ | skipping to change at line 26379 ¶ | |||
NFS4ERR_PNFS_NO_LAYOUT, | NFS4ERR_PNFS_NO_LAYOUT, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_SYMLINK, | NFS4ERR_SYMLINK, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>READDIR</c> | <tr> | |||
<c> | <td align="left">READDIR</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_COOKIE, | NFS4ERR_BAD_COOKIE, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_IO, | NFS4ERR_IO, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
skipping to change at line 26056 ¶ | skipping to change at line 26406 ¶ | |||
NFS4ERR_NOT_SAME, | NFS4ERR_NOT_SAME, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOOSMALL, | NFS4ERR_TOOSMALL, | |||
NFS4ERR_TOO_MANY_OPS | NFS4ERR_TOO_MANY_OPS | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>READLINK</c> | <tr> | |||
<c> | <td align="left">READLINK</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_IO, | NFS4ERR_IO, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>RECLAIM_COMPLETE</c> | <tr> | |||
<c> | <td align="left">RECLAIM_COMPLETE</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_COMPLETE_ALREADY, | NFS4ERR_COMPLETE_ALREADY, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_CRED, | NFS4ERR_WRONG_CRED, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>RELEASE_LOCKOWNER</c> | <tr> | |||
<c> | <td align="left">RELEASE_LOCKOWNER</td> | |||
<td align="left"> | ||||
NFS4ERR_NOTSUPP | NFS4ERR_NOTSUPP | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>REMOVE</c> | <tr> | |||
<c> | <td align="left">REMOVE</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_BADCHAR, | NFS4ERR_BADCHAR, | |||
NFS4ERR_BADNAME, | NFS4ERR_BADNAME, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_FILE_OPEN, | NFS4ERR_FILE_OPEN, | |||
NFS4ERR_GRACE, | NFS4ERR_GRACE, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
skipping to change at line 26146 ¶ | skipping to change at line 26492 ¶ | |||
NFS4ERR_NOTEMPTY, | NFS4ERR_NOTEMPTY, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_ROFS, | NFS4ERR_ROFS, | |||
NFS4ERR_SERVERFAULT, | NFS4ERR_SERVERFAULT, | |||
NFS4ERR_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS | NFS4ERR_TOO_MANY_OPS | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>RENAME</c> | <tr> | |||
<c> | <td align="left">RENAME</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_BADCHAR, | NFS4ERR_BADCHAR, | |||
NFS4ERR_BADNAME, | NFS4ERR_BADNAME, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DQUOT, | NFS4ERR_DQUOT, | |||
NFS4ERR_EXIST, | NFS4ERR_EXIST, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_FILE_OPEN, | NFS4ERR_FILE_OPEN, | |||
skipping to change at line 26185 ¶ | skipping to change at line 26530 ¶ | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_ROFS, | NFS4ERR_ROFS, | |||
NFS4ERR_SERVERFAULT, | NFS4ERR_SERVERFAULT, | |||
NFS4ERR_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONGSEC, | NFS4ERR_WRONGSEC, | |||
NFS4ERR_XDEV | NFS4ERR_XDEV | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>RENEW</c> | <tr> | |||
<c> | <td align="left">RENEW</td> | |||
<td align="left"> | ||||
NFS4ERR_NOTSUPP | NFS4ERR_NOTSUPP | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>RESTOREFH</c> | <tr> | |||
<c> | <td align="left">RESTOREFH</td> | |||
<td align="left"> | ||||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONGSEC | NFS4ERR_WRONGSEC | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>SAVEFH</c> | <tr> | |||
<c> | <td align="left">SAVEFH</td> | |||
<td align="left"> | ||||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS | NFS4ERR_TOO_MANY_OPS | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>SECINFO</c> | <tr> | |||
<c> | <td align="left">SECINFO</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_BADCHAR, | NFS4ERR_BADCHAR, | |||
NFS4ERR_BADNAME, | NFS4ERR_BADNAME, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NAMETOOLONG, | NFS4ERR_NAMETOOLONG, | |||
skipping to change at line 26260 ¶ | skipping to change at line 26601 ¶ | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
NFS4ERR_NOTDIR, | NFS4ERR_NOTDIR, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS | NFS4ERR_TOO_MANY_OPS | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>SECINFO_NO_NAME</c> | <tr> | |||
<c> | <td align="left">SECINFO_NO_NAME</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOENT, | NFS4ERR_NOENT, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
NFS4ERR_NOTDIR, | NFS4ERR_NOTDIR, | |||
NFS4ERR_NOTSUPP, | NFS4ERR_NOTSUPP, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS | NFS4ERR_TOO_MANY_OPS | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>SEQUENCE</c> | <tr> | |||
<c> | <td align="left">SEQUENCE</td> | |||
<td align="left"> | ||||
NFS4ERR_BADSESSION, | NFS4ERR_BADSESSION, | |||
NFS4ERR_BADSLOT, | NFS4ERR_BADSLOT, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_HIGH_SLOT, | NFS4ERR_BAD_HIGH_SLOT, | |||
NFS4ERR_CONN_NOT_BOUND_TO_SESSION, | NFS4ERR_CONN_NOT_BOUND_TO_SESSION, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_SEQUENCE_POS, | NFS4ERR_SEQUENCE_POS, | |||
NFS4ERR_SEQ_FALSE_RETRY, | NFS4ERR_SEQ_FALSE_RETRY, | |||
NFS4ERR_SEQ_MISORDERED, | NFS4ERR_SEQ_MISORDERED, | |||
NFS4ERR_TOO_MANY_OPS | NFS4ERR_TOO_MANY_OPS | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>SET_SSV</c> | <tr> | |||
<c> | <td align="left">SET_SSV</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_SESSION_DIGEST, | NFS4ERR_BAD_SESSION_DIGEST, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_TOO_MANY_OPS | NFS4ERR_TOO_MANY_OPS | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>SETATTR</c> | <tr> | |||
<c> | <td align="left">SETATTR</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_ADMIN_REVOKED, | NFS4ERR_ADMIN_REVOKED, | |||
NFS4ERR_ATTRNOTSUPP, | NFS4ERR_ATTRNOTSUPP, | |||
NFS4ERR_BADCHAR, | NFS4ERR_BADCHAR, | |||
NFS4ERR_BADOWNER, | NFS4ERR_BADOWNER, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DELEG_REVOKED, | NFS4ERR_DELEG_REVOKED, | |||
skipping to change at line 26368 ¶ | skipping to change at line 26705 ¶ | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_ROFS, | NFS4ERR_ROFS, | |||
NFS4ERR_SERVERFAULT, | NFS4ERR_SERVERFAULT, | |||
NFS4ERR_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_UNKNOWN_LAYOUTTYPE, | NFS4ERR_UNKNOWN_LAYOUTTYPE, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>SETCLIENTID</c> | <tr> | |||
<c> | <td align="left">SETCLIENTID</td> | |||
<td align="left"> | ||||
NFS4ERR_NOTSUPP | NFS4ERR_NOTSUPP | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>SETCLIENTID_CONFIRM</c> | <tr> | |||
<c> | <td align="left">SETCLIENTID_CONFIRM</td> | |||
<td align="left"> | ||||
NFS4ERR_NOTSUPP | NFS4ERR_NOTSUPP | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>TEST_STATEID</c> | <tr> | |||
<c> | <td align="left">TEST_STATEID</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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 | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>VERIFY</c> | <tr> | |||
<c> | <td align="left">VERIFY</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_ATTRNOTSUPP, | NFS4ERR_ATTRNOTSUPP, | |||
NFS4ERR_BADCHAR, | NFS4ERR_BADCHAR, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_GRACE, | NFS4ERR_GRACE, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_IO, | NFS4ERR_IO, | |||
skipping to change at line 26431 ¶ | skipping to change at line 26764 ¶ | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_UNKNOWN_LAYOUTTYPE, | NFS4ERR_UNKNOWN_LAYOUTTYPE, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>WANT_DELEGATION</c> | <tr> | |||
<c> | <td align="left">WANT_DELEGATION</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DELEG_ALREADY_WANTED, | NFS4ERR_DELEG_ALREADY_WANTED, | |||
NFS4ERR_FHEXPIRED, | NFS4ERR_FHEXPIRED, | |||
NFS4ERR_GRACE, | NFS4ERR_GRACE, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_IO, | NFS4ERR_IO, | |||
NFS4ERR_MOVED, | NFS4ERR_MOVED, | |||
NFS4ERR_NOFILEHANDLE, | NFS4ERR_NOFILEHANDLE, | |||
skipping to change at line 26462 ¶ | skipping to change at line 26794 ¶ | |||
NFS4ERR_RECLAIM_BAD, | NFS4ERR_RECLAIM_BAD, | |||
NFS4ERR_RECLAIM_CONFLICT, | NFS4ERR_RECLAIM_CONFLICT, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_STALE, | NFS4ERR_STALE, | |||
NFS4ERR_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>WRITE</c> | <tr> | |||
<c> | <td align="left">WRITE</td> | |||
<td align="left"> | ||||
NFS4ERR_ACCESS, | NFS4ERR_ACCESS, | |||
NFS4ERR_ADMIN_REVOKED, | NFS4ERR_ADMIN_REVOKED, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DEADSESSION, | NFS4ERR_DEADSESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_DELEG_REVOKED, | NFS4ERR_DELEG_REVOKED, | |||
NFS4ERR_DQUOT, | NFS4ERR_DQUOT, | |||
NFS4ERR_EXPIRED, | NFS4ERR_EXPIRED, | |||
NFS4ERR_FBIG, | NFS4ERR_FBIG, | |||
skipping to change at line 26503 ¶ | skipping to change at line 26834 ¶ | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_ROFS, | NFS4ERR_ROFS, | |||
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 | |||
</c> | </td> | |||
</tr> | ||||
<c /> | </tbody> | |||
<c /> | </table> | |||
</section> | ||||
<!-- ENDOFTHEERRORTABLE --> | ||||
<!-- DO NOT MOVE THIS OR THE ONE ABOVE LINE - IT MUST BE AT THE START OF TABLE - | ||||
-> | ||||
</texttable> | ||||
</section> | ||||
<!-- When adding new errors above, add them to the next section under --> | ||||
<!-- the appropriate operation; the next table for errors to --> | ||||
<!-- operations is automatically generated. --> | ||||
<section title="Callback Operations and Their Valid Errors"> | <section numbered="true" toc="default"> | |||
<t> | <name>Callback Operations and Their Valid Errors</name> | |||
<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> | |||
<texttable anchor='cb_op_error_returns'> | <table anchor="cb_op_error_returns" align="center"> | |||
<preamble> Valid Error Returns for Each Protocol | <name>Valid Error Returns for Each Protocol Callback Operation</name> | |||
Callback Operation </preamble> | <thead> | |||
<tr> | ||||
<ttcol align='left'>Callback Operation</ttcol> | <th align="left">Callback Operation</th> | |||
<ttcol align='left'>Errors</ttcol> | <th align="left">Errors</th> | |||
<!-- DO NOT MOVE THIS OR THE NEXT LINE - IT MUST BE AT THE START OF TABLE --> | </tr> | |||
<!-- STARTOFTHEERRORTABLE --> | </thead> | |||
<tbody> | ||||
<c>CB_GETATTR</c> | <tr> | |||
<c> | <td align="left">CB_GETATTR</td> | |||
<td align="left"> | ||||
NFS4ERR_BADHANDLE, | NFS4ERR_BADHANDLE, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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, | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CB_ILLEGAL</c> | <tr> | |||
<c> | <td align="left">CB_ILLEGAL</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_OP_ILLEGAL | NFS4ERR_OP_ILLEGAL | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CB_LAYOUTRECALL</c> | <tr> | |||
<c> | <td align="left">CB_LAYOUTRECALL</td> | |||
<td align="left"> | ||||
NFS4ERR_BADHANDLE, | NFS4ERR_BADHANDLE, | |||
NFS4ERR_BADIOMODE, | NFS4ERR_BADIOMODE, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_NOMATCHING_LAYOUT, | NFS4ERR_NOMATCHING_LAYOUT, | |||
NFS4ERR_NOTSUPP, | NFS4ERR_NOTSUPP, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_TOO_MANY_OPS, | NFS4ERR_TOO_MANY_OPS, | |||
NFS4ERR_UNKNOWN_LAYOUTTYPE, | NFS4ERR_UNKNOWN_LAYOUTTYPE, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CB_NOTIFY</c> | <tr> | |||
<c> | <td align="left">CB_NOTIFY</td> | |||
<td align="left"> | ||||
NFS4ERR_BADHANDLE, | NFS4ERR_BADHANDLE, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_NOTSUPP, | NFS4ERR_NOTSUPP, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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 | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CB_NOTIFY_DEVICEID</c> | <tr> | |||
<c> | <td align="left">CB_NOTIFY_DEVICEID</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_NOTSUPP, | NFS4ERR_NOTSUPP, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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 | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CB_NOTIFY_LOCK</c> | <tr> | |||
<c> | <td align="left">CB_NOTIFY_LOCK</td> | |||
<td align="left"> | ||||
NFS4ERR_BADHANDLE, | NFS4ERR_BADHANDLE, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_NOTSUPP, | NFS4ERR_NOTSUPP, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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 | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CB_PUSH_DELEG</c> | <tr> | |||
<c> | <td align="left">CB_PUSH_DELEG</td> | |||
<td align="left"> | ||||
NFS4ERR_BADHANDLE, | NFS4ERR_BADHANDLE, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_NOTSUPP, | NFS4ERR_NOTSUPP, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REJECT_DELEG, | NFS4ERR_REJECT_DELEG, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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, | |||
NFS4ERR_WRONG_TYPE | NFS4ERR_WRONG_TYPE | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CB_RECALL</c> | <tr> | |||
<c> | <td align="left">CB_RECALL</td> | |||
<td align="left"> | ||||
NFS4ERR_BADHANDLE, | NFS4ERR_BADHANDLE, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_STATEID, | NFS4ERR_BAD_STATEID, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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 | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CB_RECALL_ANY</c> | <tr> | |||
<c> | <td align="left">CB_RECALL_ANY</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_TOO_MANY_OPS | NFS4ERR_TOO_MANY_OPS | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CB_RECALLABLE_OBJ_AVAIL</c> | <tr> | |||
<c> | <td align="left">CB_RECALLABLE_OBJ_AVAIL</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_INVAL, | NFS4ERR_INVAL, | |||
NFS4ERR_NOTSUPP, | NFS4ERR_NOTSUPP, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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 | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CB_RECALL_SLOT</c> | <tr> | |||
<c> | <td align="left">CB_RECALL_SLOT</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_HIGH_SLOT, | NFS4ERR_BAD_HIGH_SLOT, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_TOO_MANY_OPS | NFS4ERR_TOO_MANY_OPS | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CB_SEQUENCE</c> | <tr> | |||
<c> | <td align="left">CB_SEQUENCE</td> | |||
<td align="left"> | ||||
NFS4ERR_BADSESSION, | NFS4ERR_BADSESSION, | |||
NFS4ERR_BADSLOT, | NFS4ERR_BADSLOT, | |||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_BAD_HIGH_SLOT, | NFS4ERR_BAD_HIGH_SLOT, | |||
NFS4ERR_CONN_NOT_BOUND_TO_SESSION, | NFS4ERR_CONN_NOT_BOUND_TO_SESSION, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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_SEQUENCE_POS, | NFS4ERR_SEQUENCE_POS, | |||
NFS4ERR_SEQ_FALSE_RETRY, | NFS4ERR_SEQ_FALSE_RETRY, | |||
NFS4ERR_SEQ_MISORDERED, | NFS4ERR_SEQ_MISORDERED, | |||
NFS4ERR_TOO_MANY_OPS | NFS4ERR_TOO_MANY_OPS | |||
</c> | </td> | |||
</tr> | ||||
<c /> | ||||
<c /> | ||||
<c>CB_WANTS_CANCELLED</c> | <tr> | |||
<c> | <td align="left">CB_WANTS_CANCELLED</td> | |||
<td align="left"> | ||||
NFS4ERR_BADXDR, | NFS4ERR_BADXDR, | |||
NFS4ERR_DELAY, | NFS4ERR_DELAY, | |||
NFS4ERR_NOTSUPP, | NFS4ERR_NOTSUPP, | |||
NFS4ERR_OP_NOT_IN_SESSION, | NFS4ERR_OP_NOT_IN_SESSION, | |||
NFS4ERR_REP_TOO_BIG, | NFS4ERR_REP_TOO_BIG, | |||
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 | |||
</c> | </td> | |||
</tr> | ||||
<c /> | </tbody> | |||
<c /> | </table> | |||
</section> | ||||
<!-- ENDOFTHEERRORTABLE --> | <section numbered="true" toc="default"> | |||
<!-- DO NOT MOVE THIS OR THE ONE ABOVE LINE - IT MUST BE AT THE START OF TABLE - | <name>Errors and the Operations That Use Them</name> | |||
-> | <table anchor="error_op_returns" align="center"> | |||
</texttable> | <name>Errors and the Operations That Use Them</name> | |||
</section> | <thead> | |||
<tr> | ||||
<!-- INCLUDE THE AUTO GENERATED ERROR TO OP TABLE --> | <th align="left">Error</th> | |||
<section title="Errors and the Operations That Use Them"> | <th align="left">Operations</th> | |||
<texttable anchor='error_op_returns'> | </tr> | |||
<ttcol align='left'>Error</ttcol> | </thead> | |||
<ttcol align='left'>Operations</ttcol> | <tbody> | |||
<tr> | ||||
<c>NFS4ERR_ACCESS</c> | <td align="left">NFS4ERR_ACCESS</td> | |||
<c> | <td align="left"> | |||
ACCESS, | ACCESS, | |||
COMMIT, | COMMIT, | |||
CREATE, | CREATE, | |||
GETATTR, | GETATTR, | |||
GET_DIR_DELEGATION, | GET_DIR_DELEGATION, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LAYOUTGET, | LAYOUTGET, | |||
LINK, | LINK, | |||
LOCK, | LOCK, | |||
LOCKT, | LOCKT, | |||
skipping to change at line 26807 ¶ | skipping to change at line 27120 ¶ | |||
READ, | READ, | |||
READDIR, | READDIR, | |||
READLINK, | READLINK, | |||
REMOVE, | REMOVE, | |||
RENAME, | RENAME, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SETATTR, | SETATTR, | |||
VERIFY, | VERIFY, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_ADMIN_REVOKED</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_ADMIN_REVOKED</td> | |||
<td align="left"> | ||||
CLOSE, | CLOSE, | |||
DELEGRETURN, | DELEGRETURN, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LAYOUTGET, | LAYOUTGET, | |||
LAYOUTRETURN, | LAYOUTRETURN, | |||
LOCK, | LOCK, | |||
LOCKU, | LOCKU, | |||
OPEN, | OPEN, | |||
OPEN_DOWNGRADE, | OPEN_DOWNGRADE, | |||
READ, | READ, | |||
SETATTR, | SETATTR, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_ATTRNOTSUPP</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_ATTRNOTSUPP</td> | |||
<td align="left"> | ||||
CREATE, | CREATE, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
NVERIFY, | NVERIFY, | |||
OPEN, | OPEN, | |||
SETATTR, | SETATTR, | |||
VERIFY | VERIFY | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BACK_CHAN_BUSY</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BACK_CHAN_BUSY</td> | |||
<td align="left"> | ||||
DESTROY_SESSION | DESTROY_SESSION | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BADCHAR</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BADCHAR</td> | |||
<td align="left"> | ||||
CREATE, | CREATE, | |||
EXCHANGE_ID, | EXCHANGE_ID, | |||
LINK, | LINK, | |||
LOOKUP, | LOOKUP, | |||
NVERIFY, | NVERIFY, | |||
OPEN, | OPEN, | |||
REMOVE, | REMOVE, | |||
RENAME, | RENAME, | |||
SECINFO, | SECINFO, | |||
SETATTR, | SETATTR, | |||
VERIFY | VERIFY | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BADHANDLE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BADHANDLE</td> | |||
<td align="left"> | ||||
CB_GETATTR, | CB_GETATTR, | |||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
CB_NOTIFY, | CB_NOTIFY, | |||
CB_NOTIFY_LOCK, | CB_NOTIFY_LOCK, | |||
CB_PUSH_DELEG, | CB_PUSH_DELEG, | |||
CB_RECALL, | CB_RECALL, | |||
PUTFH | PUTFH | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BADIOMODE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BADIOMODE</td> | |||
<td align="left"> | ||||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LAYOUTGET | LAYOUTGET | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BADLAYOUT</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BADLAYOUT</td> | |||
<td align="left"> | ||||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LAYOUTGET | LAYOUTGET | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BADNAME</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BADNAME</td> | |||
<td align="left"> | ||||
CREATE, | CREATE, | |||
LINK, | LINK, | |||
LOOKUP, | LOOKUP, | |||
OPEN, | OPEN, | |||
REMOVE, | REMOVE, | |||
RENAME, | RENAME, | |||
SECINFO | SECINFO | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BADOWNER</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BADOWNER</td> | |||
<td align="left"> | ||||
CREATE, | CREATE, | |||
OPEN, | OPEN, | |||
SETATTR | SETATTR | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BADSESSION</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BADSESSION</td> | |||
<td align="left"> | ||||
BIND_CONN_TO_SESSION, | BIND_CONN_TO_SESSION, | |||
CB_SEQUENCE, | CB_SEQUENCE, | |||
DESTROY_SESSION, | DESTROY_SESSION, | |||
SEQUENCE | SEQUENCE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BADSLOT</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BADSLOT</td> | |||
<td align="left"> | ||||
CB_SEQUENCE, | CB_SEQUENCE, | |||
SEQUENCE | SEQUENCE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BADTYPE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BADTYPE</td> | |||
<td align="left"> | ||||
CREATE | CREATE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BADXDR</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BADXDR</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
BACKCHANNEL_CTL, | BACKCHANNEL_CTL, | |||
BIND_CONN_TO_SESSION, | BIND_CONN_TO_SESSION, | |||
CB_GETATTR, | CB_GETATTR, | |||
CB_ILLEGAL, | CB_ILLEGAL, | |||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
CB_NOTIFY, | CB_NOTIFY, | |||
CB_NOTIFY_DEVICEID, | CB_NOTIFY_DEVICEID, | |||
CB_NOTIFY_LOCK, | CB_NOTIFY_LOCK, | |||
CB_PUSH_DELEG, | CB_PUSH_DELEG, | |||
skipping to change at line 27002 ¶ | skipping to change at line 27315 ¶ | |||
RENAME, | RENAME, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SEQUENCE, | SEQUENCE, | |||
SETATTR, | SETATTR, | |||
SET_SSV, | SET_SSV, | |||
TEST_STATEID, | TEST_STATEID, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BAD_COOKIE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BAD_COOKIE</td> | |||
<td align="left"> | ||||
GETDEVICELIST, | GETDEVICELIST, | |||
READDIR | READDIR | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BAD_HIGH_SLOT</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BAD_HIGH_SLOT</td> | |||
<td align="left"> | ||||
CB_RECALL_SLOT, | CB_RECALL_SLOT, | |||
CB_SEQUENCE, | CB_SEQUENCE, | |||
SEQUENCE | SEQUENCE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BAD_RANGE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BAD_RANGE</td> | |||
<td align="left"> | ||||
LOCK, | LOCK, | |||
LOCKT, | LOCKT, | |||
LOCKU | LOCKU | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BAD_SESSION_DIGEST</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BAD_SESSION_DIGEST</td> | |||
<td align="left"> | ||||
BIND_CONN_TO_SESSION, | BIND_CONN_TO_SESSION, | |||
SET_SSV | SET_SSV | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_BAD_STATEID</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_BAD_STATEID</td> | |||
<td align="left"> | ||||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
CB_NOTIFY, | CB_NOTIFY, | |||
CB_NOTIFY_LOCK, | CB_NOTIFY_LOCK, | |||
CB_RECALL, | CB_RECALL, | |||
CLOSE, | CLOSE, | |||
DELEGRETURN, | DELEGRETURN, | |||
FREE_STATEID, | FREE_STATEID, | |||
LAYOUTGET, | LAYOUTGET, | |||
LAYOUTRETURN, | LAYOUTRETURN, | |||
LOCK, | LOCK, | |||
LOCKU, | LOCKU, | |||
OPEN, | OPEN, | |||
OPEN_DOWNGRADE, | OPEN_DOWNGRADE, | |||
READ, | READ, | |||
SETATTR, | SETATTR, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_CB_PATH_DOWN</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_CB_PATH_DOWN</td> | |||
<td align="left"> | ||||
DESTROY_SESSION | DESTROY_SESSION | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_CLID_INUSE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_CLID_INUSE</td> | |||
<td align="left"> | ||||
CREATE_SESSION, | CREATE_SESSION, | |||
EXCHANGE_ID | EXCHANGE_ID | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_CLIENTID_BUSY</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_CLIENTID_BUSY</td> | |||
<td align="left"> | ||||
DESTROY_CLIENTID | DESTROY_CLIENTID | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_COMPLETE_ALREADY</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_COMPLETE_ALREADY</td> | |||
<td align="left"> | ||||
RECLAIM_COMPLETE | RECLAIM_COMPLETE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_CONN_NOT_BOUND_TO_SESSION</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_CONN_NOT_BOUND_TO_SESSION</td> | |||
<td align="left"> | ||||
CB_SEQUENCE, | CB_SEQUENCE, | |||
DESTROY_SESSION, | DESTROY_SESSION, | |||
SEQUENCE | SEQUENCE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_DEADLOCK</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_DEADLOCK</td> | |||
<td align="left"> | ||||
LOCK | LOCK | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_DEADSESSION</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_DEADSESSION</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
BACKCHANNEL_CTL, | BACKCHANNEL_CTL, | |||
BIND_CONN_TO_SESSION, | BIND_CONN_TO_SESSION, | |||
CLOSE, | CLOSE, | |||
COMMIT, | COMMIT, | |||
CREATE, | CREATE, | |||
CREATE_SESSION, | CREATE_SESSION, | |||
DELEGPURGE, | DELEGPURGE, | |||
DELEGRETURN, | DELEGRETURN, | |||
DESTROY_CLIENTID, | DESTROY_CLIENTID, | |||
skipping to change at line 27159 ¶ | skipping to change at line 27472 ¶ | |||
SAVEFH, | SAVEFH, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SEQUENCE, | SEQUENCE, | |||
SETATTR, | SETATTR, | |||
SET_SSV, | SET_SSV, | |||
TEST_STATEID, | TEST_STATEID, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_DELAY</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_DELAY</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
BACKCHANNEL_CTL, | BACKCHANNEL_CTL, | |||
BIND_CONN_TO_SESSION, | BIND_CONN_TO_SESSION, | |||
CB_GETATTR, | CB_GETATTR, | |||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
CB_NOTIFY, | CB_NOTIFY, | |||
CB_NOTIFY_DEVICEID, | CB_NOTIFY_DEVICEID, | |||
CB_NOTIFY_LOCK, | CB_NOTIFY_LOCK, | |||
CB_PUSH_DELEG, | CB_PUSH_DELEG, | |||
CB_RECALL, | CB_RECALL, | |||
skipping to change at line 27225 ¶ | skipping to change at line 27538 ¶ | |||
RENAME, | RENAME, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SEQUENCE, | SEQUENCE, | |||
SETATTR, | SETATTR, | |||
SET_SSV, | SET_SSV, | |||
TEST_STATEID, | TEST_STATEID, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_DELEG_ALREADY_WANTED</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_DELEG_ALREADY_WANTED</td> | |||
<td align="left"> | ||||
OPEN, | OPEN, | |||
WANT_DELEGATION | WANT_DELEGATION | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_DELEG_REVOKED</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_DELEG_REVOKED</td> | |||
<td align="left"> | ||||
DELEGRETURN, | DELEGRETURN, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LAYOUTGET, | LAYOUTGET, | |||
LAYOUTRETURN, | LAYOUTRETURN, | |||
OPEN, | OPEN, | |||
READ, | READ, | |||
SETATTR, | SETATTR, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_DENIED</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_DENIED</td> | |||
<td align="left"> | ||||
LOCK, | LOCK, | |||
LOCKT | LOCKT | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_DIRDELEG_UNAVAIL</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_DIRDELEG_UNAVAIL</td> | |||
<td align="left"> | ||||
GET_DIR_DELEGATION | GET_DIR_DELEGATION | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_DQUOT</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_DQUOT</td> | |||
<td align="left"> | ||||
CREATE, | CREATE, | |||
LAYOUTGET, | LAYOUTGET, | |||
LINK, | LINK, | |||
OPEN, | OPEN, | |||
OPENATTR, | OPENATTR, | |||
RENAME, | RENAME, | |||
SETATTR, | SETATTR, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_ENCR_ALG_UNSUPP</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_ENCR_ALG_UNSUPP</td> | |||
<td align="left"> | ||||
EXCHANGE_ID | EXCHANGE_ID | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_EXIST</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_EXIST</td> | |||
<td align="left"> | ||||
CREATE, | CREATE, | |||
LINK, | LINK, | |||
OPEN, | OPEN, | |||
RENAME | RENAME | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_EXPIRED</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_EXPIRED</td> | |||
<td align="left"> | ||||
CLOSE, | CLOSE, | |||
DELEGRETURN, | DELEGRETURN, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LAYOUTRETURN, | LAYOUTRETURN, | |||
LOCK, | LOCK, | |||
LOCKU, | LOCKU, | |||
OPEN, | OPEN, | |||
OPEN_DOWNGRADE, | OPEN_DOWNGRADE, | |||
READ, | READ, | |||
SETATTR, | SETATTR, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_FBIG</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_FBIG</td> | |||
<td align="left"> | ||||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
OPEN, | OPEN, | |||
SETATTR, | SETATTR, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_FHEXPIRED</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_FHEXPIRED</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
CLOSE, | CLOSE, | |||
COMMIT, | COMMIT, | |||
CREATE, | CREATE, | |||
DELEGRETURN, | DELEGRETURN, | |||
GETATTR, | GETATTR, | |||
GETDEVICELIST, | GETDEVICELIST, | |||
GETFH, | GETFH, | |||
GET_DIR_DELEGATION, | GET_DIR_DELEGATION, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
skipping to change at line 27362 ¶ | skipping to change at line 27675 ¶ | |||
REMOVE, | REMOVE, | |||
RENAME, | RENAME, | |||
RESTOREFH, | RESTOREFH, | |||
SAVEFH, | SAVEFH, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SETATTR, | SETATTR, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_FILE_OPEN</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_FILE_OPEN</td> | |||
<td align="left"> | ||||
LINK, | LINK, | |||
REMOVE, | REMOVE, | |||
RENAME | RENAME | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_GRACE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_GRACE</td> | |||
<td align="left"> | ||||
GETATTR, | GETATTR, | |||
GET_DIR_DELEGATION, | GET_DIR_DELEGATION, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LAYOUTGET, | LAYOUTGET, | |||
LAYOUTRETURN, | LAYOUTRETURN, | |||
LINK, | LINK, | |||
LOCK, | LOCK, | |||
LOCKT, | LOCKT, | |||
NVERIFY, | NVERIFY, | |||
OPEN, | OPEN, | |||
READ, | READ, | |||
REMOVE, | REMOVE, | |||
RENAME, | RENAME, | |||
SETATTR, | SETATTR, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_HASH_ALG_UNSUPP</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_HASH_ALG_UNSUPP</td> | |||
<td align="left"> | ||||
EXCHANGE_ID | EXCHANGE_ID | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_INVAL</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_INVAL</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
BACKCHANNEL_CTL, | BACKCHANNEL_CTL, | |||
BIND_CONN_TO_SESSION, | BIND_CONN_TO_SESSION, | |||
CB_GETATTR, | CB_GETATTR, | |||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
CB_NOTIFY, | CB_NOTIFY, | |||
CB_NOTIFY_DEVICEID, | CB_NOTIFY_DEVICEID, | |||
CB_PUSH_DELEG, | CB_PUSH_DELEG, | |||
CB_RECALLABLE_OBJ_AVAIL, | CB_RECALLABLE_OBJ_AVAIL, | |||
CB_RECALL_ANY, | CB_RECALL_ANY, | |||
skipping to change at line 27449 ¶ | skipping to change at line 27762 ¶ | |||
RECLAIM_COMPLETE, | RECLAIM_COMPLETE, | |||
REMOVE, | REMOVE, | |||
RENAME, | RENAME, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SETATTR, | SETATTR, | |||
SET_SSV, | SET_SSV, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_IO</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_IO</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
COMMIT, | COMMIT, | |||
CREATE, | CREATE, | |||
GETATTR, | GETATTR, | |||
GETDEVICELIST, | GETDEVICELIST, | |||
GET_DIR_DELEGATION, | GET_DIR_DELEGATION, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LAYOUTGET, | LAYOUTGET, | |||
LINK, | LINK, | |||
LOOKUP, | LOOKUP, | |||
skipping to change at line 27478 ¶ | skipping to change at line 27791 ¶ | |||
OPENATTR, | OPENATTR, | |||
READ, | READ, | |||
READDIR, | READDIR, | |||
READLINK, | READLINK, | |||
REMOVE, | REMOVE, | |||
RENAME, | RENAME, | |||
SETATTR, | SETATTR, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_ISDIR</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_ISDIR</td> | |||
<td align="left"> | ||||
COMMIT, | COMMIT, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LAYOUTRETURN, | LAYOUTRETURN, | |||
LINK, | LINK, | |||
LOCK, | LOCK, | |||
LOCKT, | LOCKT, | |||
OPEN, | OPEN, | |||
READ, | READ, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_LAYOUTTRYLATER</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_LAYOUTTRYLATER</td> | |||
<td align="left"> | ||||
LAYOUTGET | LAYOUTGET | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_LAYOUTUNAVAILABLE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_LAYOUTUNAVAILABLE</td> | |||
<td align="left"> | ||||
LAYOUTGET | LAYOUTGET | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_LOCKED</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_LOCKED</td> | |||
<td align="left"> | ||||
LAYOUTGET, | LAYOUTGET, | |||
READ, | READ, | |||
SETATTR, | SETATTR, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_LOCKS_HELD</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_LOCKS_HELD</td> | |||
<td align="left"> | ||||
CLOSE, | CLOSE, | |||
FREE_STATEID | FREE_STATEID | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_LOCK_NOTSUPP</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_LOCK_NOTSUPP</td> | |||
<td align="left"> | ||||
LOCK | LOCK | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_LOCK_RANGE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_LOCK_RANGE</td> | |||
<td align="left"> | ||||
LOCK, | LOCK, | |||
LOCKT, | LOCKT, | |||
LOCKU | LOCKU | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_MLINK</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_MLINK</td> | |||
<td align="left"> | ||||
CREATE, | CREATE, | |||
LINK, | LINK, | |||
RENAME | RENAME | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_MOVED</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_MOVED</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
CLOSE, | CLOSE, | |||
COMMIT, | COMMIT, | |||
CREATE, | CREATE, | |||
DELEGRETURN, | DELEGRETURN, | |||
GETATTR, | GETATTR, | |||
GETFH, | GETFH, | |||
GET_DIR_DELEGATION, | GET_DIR_DELEGATION, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LAYOUTGET, | LAYOUTGET, | |||
skipping to change at line 27592 ¶ | skipping to change at line 27905 ¶ | |||
REMOVE, | REMOVE, | |||
RENAME, | RENAME, | |||
RESTOREFH, | RESTOREFH, | |||
SAVEFH, | SAVEFH, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SETATTR, | SETATTR, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_NAMETOOLONG</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_NAMETOOLONG</td> | |||
<td align="left"> | ||||
CREATE, | CREATE, | |||
LINK, | LINK, | |||
LOOKUP, | LOOKUP, | |||
OPEN, | OPEN, | |||
REMOVE, | REMOVE, | |||
RENAME, | RENAME, | |||
SECINFO | SECINFO | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_NOENT</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_NOENT</td> | |||
<td align="left"> | ||||
BACKCHANNEL_CTL, | BACKCHANNEL_CTL, | |||
CREATE_SESSION, | CREATE_SESSION, | |||
EXCHANGE_ID, | EXCHANGE_ID, | |||
GETDEVICEINFO, | GETDEVICEINFO, | |||
LOOKUP, | LOOKUP, | |||
LOOKUPP, | LOOKUPP, | |||
OPEN, | OPEN, | |||
OPENATTR, | OPENATTR, | |||
REMOVE, | REMOVE, | |||
RENAME, | RENAME, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME | SECINFO_NO_NAME | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_NOFILEHANDLE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_NOFILEHANDLE</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
CLOSE, | CLOSE, | |||
COMMIT, | COMMIT, | |||
CREATE, | CREATE, | |||
DELEGRETURN, | DELEGRETURN, | |||
GETATTR, | GETATTR, | |||
GETDEVICELIST, | GETDEVICELIST, | |||
GETFH, | GETFH, | |||
GET_DIR_DELEGATION, | GET_DIR_DELEGATION, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
skipping to change at line 27665 ¶ | skipping to change at line 27978 ¶ | |||
REMOVE, | REMOVE, | |||
RENAME, | RENAME, | |||
RESTOREFH, | RESTOREFH, | |||
SAVEFH, | SAVEFH, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SETATTR, | SETATTR, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_NOMATCHING_LAYOUT</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_NOMATCHING_LAYOUT</td> | |||
<td align="left"> | ||||
CB_LAYOUTRECALL | CB_LAYOUTRECALL | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_NOSPC</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_NOSPC</td> | |||
<td align="left"> | ||||
CREATE, | CREATE, | |||
CREATE_SESSION, | CREATE_SESSION, | |||
LAYOUTGET, | LAYOUTGET, | |||
LINK, | LINK, | |||
OPEN, | OPEN, | |||
OPENATTR, | OPENATTR, | |||
RENAME, | RENAME, | |||
SETATTR, | SETATTR, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_NOTDIR</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_NOTDIR</td> | |||
<td align="left"> | ||||
CREATE, | CREATE, | |||
GET_DIR_DELEGATION, | GET_DIR_DELEGATION, | |||
LINK, | LINK, | |||
LOOKUP, | LOOKUP, | |||
LOOKUPP, | LOOKUPP, | |||
OPEN, | OPEN, | |||
READDIR, | READDIR, | |||
REMOVE, | REMOVE, | |||
RENAME, | RENAME, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME | SECINFO_NO_NAME | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_NOTEMPTY</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_NOTEMPTY</td> | |||
<td align="left"> | ||||
REMOVE, | REMOVE, | |||
RENAME | RENAME | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_NOTSUPP</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_NOTSUPP</td> | |||
<td align="left"> | ||||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
CB_NOTIFY, | CB_NOTIFY, | |||
CB_NOTIFY_DEVICEID, | CB_NOTIFY_DEVICEID, | |||
CB_NOTIFY_LOCK, | CB_NOTIFY_LOCK, | |||
CB_PUSH_DELEG, | CB_PUSH_DELEG, | |||
CB_RECALLABLE_OBJ_AVAIL, | CB_RECALLABLE_OBJ_AVAIL, | |||
CB_WANTS_CANCELLED, | CB_WANTS_CANCELLED, | |||
DELEGPURGE, | DELEGPURGE, | |||
DELEGRETURN, | DELEGRETURN, | |||
GETDEVICEINFO, | GETDEVICEINFO, | |||
skipping to change at line 27742 ¶ | skipping to change at line 28055 ¶ | |||
LAYOUTRETURN, | LAYOUTRETURN, | |||
LINK, | LINK, | |||
OPENATTR, | OPENATTR, | |||
OPEN_CONFIRM, | OPEN_CONFIRM, | |||
RELEASE_LOCKOWNER, | RELEASE_LOCKOWNER, | |||
RENEW, | RENEW, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SETCLIENTID, | SETCLIENTID, | |||
SETCLIENTID_CONFIRM, | SETCLIENTID_CONFIRM, | |||
WANT_DELEGATION | WANT_DELEGATION | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_NOT_ONLY_OP</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_NOT_ONLY_OP</td> | |||
<td align="left"> | ||||
BIND_CONN_TO_SESSION, | BIND_CONN_TO_SESSION, | |||
CREATE_SESSION, | CREATE_SESSION, | |||
DESTROY_CLIENTID, | DESTROY_CLIENTID, | |||
DESTROY_SESSION, | DESTROY_SESSION, | |||
EXCHANGE_ID | EXCHANGE_ID | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_NOT_SAME</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_NOT_SAME</td> | |||
<td align="left"> | ||||
EXCHANGE_ID, | EXCHANGE_ID, | |||
GETDEVICELIST, | GETDEVICELIST, | |||
READDIR, | READDIR, | |||
VERIFY | VERIFY | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_NO_GRACE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_NO_GRACE</td> | |||
<td align="left"> | ||||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LAYOUTRETURN, | LAYOUTRETURN, | |||
LOCK, | LOCK, | |||
OPEN, | OPEN, | |||
WANT_DELEGATION | WANT_DELEGATION | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_OLD_STATEID</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_OLD_STATEID</td> | |||
<td align="left"> | ||||
CLOSE, | CLOSE, | |||
DELEGRETURN, | DELEGRETURN, | |||
FREE_STATEID, | FREE_STATEID, | |||
LAYOUTGET, | LAYOUTGET, | |||
LAYOUTRETURN, | LAYOUTRETURN, | |||
LOCK, | LOCK, | |||
LOCKU, | LOCKU, | |||
OPEN, | OPEN, | |||
OPEN_DOWNGRADE, | OPEN_DOWNGRADE, | |||
READ, | READ, | |||
SETATTR, | SETATTR, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_OPENMODE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_OPENMODE</td> | |||
<td align="left"> | ||||
LAYOUTGET, | LAYOUTGET, | |||
LOCK, | LOCK, | |||
READ, | READ, | |||
SETATTR, | SETATTR, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_OP_ILLEGAL</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_OP_ILLEGAL</td> | |||
<td align="left"> | ||||
CB_ILLEGAL, | CB_ILLEGAL, | |||
ILLEGAL | ILLEGAL | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_OP_NOT_IN_SESSION</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_OP_NOT_IN_SESSION</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
BACKCHANNEL_CTL, | BACKCHANNEL_CTL, | |||
CB_GETATTR, | CB_GETATTR, | |||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
CB_NOTIFY, | CB_NOTIFY, | |||
CB_NOTIFY_DEVICEID, | CB_NOTIFY_DEVICEID, | |||
CB_NOTIFY_LOCK, | CB_NOTIFY_LOCK, | |||
CB_PUSH_DELEG, | CB_PUSH_DELEG, | |||
CB_RECALL, | CB_RECALL, | |||
CB_RECALLABLE_OBJ_AVAIL, | CB_RECALLABLE_OBJ_AVAIL, | |||
skipping to change at line 27873 ¶ | skipping to change at line 28186 ¶ | |||
RESTOREFH, | RESTOREFH, | |||
SAVEFH, | SAVEFH, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SETATTR, | SETATTR, | |||
SET_SSV, | SET_SSV, | |||
TEST_STATEID, | TEST_STATEID, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_PERM</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_PERM</td> | |||
<td align="left"> | ||||
CREATE, | CREATE, | |||
OPEN, | OPEN, | |||
SETATTR | SETATTR | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_PNFS_IO_HOLE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_PNFS_IO_HOLE</td> | |||
<td align="left"> | ||||
READ, | READ, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_PNFS_NO_LAYOUT</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_PNFS_NO_LAYOUT</td> | |||
<td align="left"> | ||||
READ, | READ, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_RECALLCONFLICT</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_RECALLCONFLICT</td> | |||
<td align="left"> | ||||
LAYOUTGET, | LAYOUTGET, | |||
WANT_DELEGATION | WANT_DELEGATION | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_RECLAIM_BAD</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_RECLAIM_BAD</td> | |||
<td align="left"> | ||||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LOCK, | LOCK, | |||
OPEN, | OPEN, | |||
WANT_DELEGATION | WANT_DELEGATION | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_RECLAIM_CONFLICT</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_RECLAIM_CONFLICT</td> | |||
<td align="left"> | ||||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LOCK, | LOCK, | |||
OPEN, | OPEN, | |||
WANT_DELEGATION | WANT_DELEGATION | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_REJECT_DELEG</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_REJECT_DELEG</td> | |||
<td align="left"> | ||||
CB_PUSH_DELEG | CB_PUSH_DELEG | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_REP_TOO_BIG</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_REP_TOO_BIG</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
BACKCHANNEL_CTL, | BACKCHANNEL_CTL, | |||
BIND_CONN_TO_SESSION, | BIND_CONN_TO_SESSION, | |||
CB_GETATTR, | CB_GETATTR, | |||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
CB_NOTIFY, | CB_NOTIFY, | |||
CB_NOTIFY_DEVICEID, | CB_NOTIFY_DEVICEID, | |||
CB_NOTIFY_LOCK, | CB_NOTIFY_LOCK, | |||
CB_PUSH_DELEG, | CB_PUSH_DELEG, | |||
CB_RECALL, | CB_RECALL, | |||
skipping to change at line 28001 ¶ | skipping to change at line 28314 ¶ | |||
SAVEFH, | SAVEFH, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SEQUENCE, | SEQUENCE, | |||
SETATTR, | SETATTR, | |||
SET_SSV, | SET_SSV, | |||
TEST_STATEID, | TEST_STATEID, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_REP_TOO_BIG_TO_CACHE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_REP_TOO_BIG_TO_CACHE</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
BACKCHANNEL_CTL, | BACKCHANNEL_CTL, | |||
BIND_CONN_TO_SESSION, | BIND_CONN_TO_SESSION, | |||
CB_GETATTR, | CB_GETATTR, | |||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
CB_NOTIFY, | CB_NOTIFY, | |||
CB_NOTIFY_DEVICEID, | CB_NOTIFY_DEVICEID, | |||
CB_NOTIFY_LOCK, | CB_NOTIFY_LOCK, | |||
CB_PUSH_DELEG, | CB_PUSH_DELEG, | |||
CB_RECALL, | CB_RECALL, | |||
skipping to change at line 28069 ¶ | skipping to change at line 28382 ¶ | |||
SAVEFH, | SAVEFH, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SEQUENCE, | SEQUENCE, | |||
SETATTR, | SETATTR, | |||
SET_SSV, | SET_SSV, | |||
TEST_STATEID, | TEST_STATEID, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_REQ_TOO_BIG</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_REQ_TOO_BIG</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
BACKCHANNEL_CTL, | BACKCHANNEL_CTL, | |||
BIND_CONN_TO_SESSION, | BIND_CONN_TO_SESSION, | |||
CB_GETATTR, | CB_GETATTR, | |||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
CB_NOTIFY, | CB_NOTIFY, | |||
CB_NOTIFY_DEVICEID, | CB_NOTIFY_DEVICEID, | |||
CB_NOTIFY_LOCK, | CB_NOTIFY_LOCK, | |||
CB_PUSH_DELEG, | CB_PUSH_DELEG, | |||
CB_RECALL, | CB_RECALL, | |||
skipping to change at line 28137 ¶ | skipping to change at line 28450 ¶ | |||
SAVEFH, | SAVEFH, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SEQUENCE, | SEQUENCE, | |||
SETATTR, | SETATTR, | |||
SET_SSV, | SET_SSV, | |||
TEST_STATEID, | TEST_STATEID, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_RETRY_UNCACHED_REP</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_RETRY_UNCACHED_REP</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
BACKCHANNEL_CTL, | BACKCHANNEL_CTL, | |||
BIND_CONN_TO_SESSION, | BIND_CONN_TO_SESSION, | |||
CB_GETATTR, | CB_GETATTR, | |||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
CB_NOTIFY, | CB_NOTIFY, | |||
CB_NOTIFY_DEVICEID, | CB_NOTIFY_DEVICEID, | |||
CB_NOTIFY_LOCK, | CB_NOTIFY_LOCK, | |||
CB_PUSH_DELEG, | CB_PUSH_DELEG, | |||
CB_RECALL, | CB_RECALL, | |||
skipping to change at line 28205 ¶ | skipping to change at line 28518 ¶ | |||
SAVEFH, | SAVEFH, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SEQUENCE, | SEQUENCE, | |||
SETATTR, | SETATTR, | |||
SET_SSV, | SET_SSV, | |||
TEST_STATEID, | TEST_STATEID, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_ROFS</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_ROFS</td> | |||
<td align="left"> | ||||
CREATE, | CREATE, | |||
LINK, | LINK, | |||
LOCK, | LOCK, | |||
LOCKT, | LOCKT, | |||
OPEN, | OPEN, | |||
OPENATTR, | OPENATTR, | |||
OPEN_DOWNGRADE, | OPEN_DOWNGRADE, | |||
REMOVE, | REMOVE, | |||
RENAME, | RENAME, | |||
SETATTR, | SETATTR, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_SAME</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_SAME</td> | |||
<td align="left"> | ||||
NVERIFY | NVERIFY | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_SEQUENCE_POS</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_SEQUENCE_POS</td> | |||
<td align="left"> | ||||
CB_SEQUENCE, | CB_SEQUENCE, | |||
SEQUENCE | SEQUENCE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_SEQ_FALSE_RETRY</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_SEQ_FALSE_RETRY</td> | |||
<td align="left"> | ||||
CB_SEQUENCE, | CB_SEQUENCE, | |||
SEQUENCE | SEQUENCE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_SEQ_MISORDERED</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_SEQ_MISORDERED</td> | |||
<td align="left"> | ||||
CB_SEQUENCE, | CB_SEQUENCE, | |||
CREATE_SESSION, | CREATE_SESSION, | |||
SEQUENCE | SEQUENCE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_SERVERFAULT</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_SERVERFAULT</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
BIND_CONN_TO_SESSION, | BIND_CONN_TO_SESSION, | |||
CB_GETATTR, | CB_GETATTR, | |||
CB_NOTIFY, | CB_NOTIFY, | |||
CB_NOTIFY_DEVICEID, | CB_NOTIFY_DEVICEID, | |||
CB_NOTIFY_LOCK, | CB_NOTIFY_LOCK, | |||
CB_PUSH_DELEG, | CB_PUSH_DELEG, | |||
CB_RECALL, | CB_RECALL, | |||
CB_RECALLABLE_OBJ_AVAIL, | CB_RECALLABLE_OBJ_AVAIL, | |||
CB_WANTS_CANCELLED, | CB_WANTS_CANCELLED, | |||
skipping to change at line 28314 ¶ | skipping to change at line 28627 ¶ | |||
RENAME, | RENAME, | |||
RESTOREFH, | RESTOREFH, | |||
SAVEFH, | SAVEFH, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SETATTR, | SETATTR, | |||
TEST_STATEID, | TEST_STATEID, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_SHARE_DENIED</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_SHARE_DENIED</td> | |||
<td align="left"> | ||||
OPEN | OPEN | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_STALE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_STALE</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
CLOSE, | CLOSE, | |||
COMMIT, | COMMIT, | |||
CREATE, | CREATE, | |||
DELEGRETURN, | DELEGRETURN, | |||
GETATTR, | GETATTR, | |||
GETFH, | GETFH, | |||
GET_DIR_DELEGATION, | GET_DIR_DELEGATION, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LAYOUTGET, | LAYOUTGET, | |||
skipping to change at line 28363 ¶ | skipping to change at line 28676 ¶ | |||
REMOVE, | REMOVE, | |||
RENAME, | RENAME, | |||
RESTOREFH, | RESTOREFH, | |||
SAVEFH, | SAVEFH, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SETATTR, | SETATTR, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_STALE_CLIENTID</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_STALE_CLIENTID</td> | |||
<td align="left"> | ||||
CREATE_SESSION, | CREATE_SESSION, | |||
DESTROY_CLIENTID, | DESTROY_CLIENTID, | |||
DESTROY_SESSION | DESTROY_SESSION | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_SYMLINK</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_SYMLINK</td> | |||
<td align="left"> | ||||
COMMIT, | COMMIT, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LINK, | LINK, | |||
LOCK, | LOCK, | |||
LOCKT, | LOCKT, | |||
LOOKUP, | LOOKUP, | |||
LOOKUPP, | LOOKUPP, | |||
OPEN, | OPEN, | |||
READ, | READ, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_TOOSMALL</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_TOOSMALL</td> | |||
<td align="left"> | ||||
CREATE_SESSION, | CREATE_SESSION, | |||
GETDEVICEINFO, | GETDEVICEINFO, | |||
LAYOUTGET, | LAYOUTGET, | |||
READDIR | READDIR | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_TOO_MANY_OPS</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_TOO_MANY_OPS</td> | |||
<td align="left"> | ||||
ACCESS, | ACCESS, | |||
BACKCHANNEL_CTL, | BACKCHANNEL_CTL, | |||
BIND_CONN_TO_SESSION, | BIND_CONN_TO_SESSION, | |||
CB_GETATTR, | CB_GETATTR, | |||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
CB_NOTIFY, | CB_NOTIFY, | |||
CB_NOTIFY_DEVICEID, | CB_NOTIFY_DEVICEID, | |||
CB_NOTIFY_LOCK, | CB_NOTIFY_LOCK, | |||
CB_PUSH_DELEG, | CB_PUSH_DELEG, | |||
CB_RECALL, | CB_RECALL, | |||
skipping to change at line 28466 ¶ | skipping to change at line 28779 ¶ | |||
SAVEFH, | SAVEFH, | |||
SECINFO, | SECINFO, | |||
SECINFO_NO_NAME, | SECINFO_NO_NAME, | |||
SEQUENCE, | SEQUENCE, | |||
SETATTR, | SETATTR, | |||
SET_SSV, | SET_SSV, | |||
TEST_STATEID, | TEST_STATEID, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_UNKNOWN_LAYOUTTYPE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_UNKNOWN_LAYOUTTYPE</td> | |||
<td align="left"> | ||||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
GETDEVICEINFO, | GETDEVICEINFO, | |||
GETDEVICELIST, | GETDEVICELIST, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LAYOUTGET, | LAYOUTGET, | |||
LAYOUTRETURN, | LAYOUTRETURN, | |||
NVERIFY, | NVERIFY, | |||
SETATTR, | SETATTR, | |||
VERIFY | VERIFY | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_UNSAFE_COMPOUND</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_UNSAFE_COMPOUND</td> | |||
<td align="left"> | ||||
CREATE, | CREATE, | |||
OPEN, | OPEN, | |||
OPENATTR | OPENATTR | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_WRONGSEC</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_WRONGSEC</td> | |||
<td align="left"> | ||||
LINK, | LINK, | |||
LOOKUP, | LOOKUP, | |||
LOOKUPP, | LOOKUPP, | |||
OPEN, | OPEN, | |||
PUTFH, | PUTFH, | |||
PUTPUBFH, | PUTPUBFH, | |||
PUTROOTFH, | PUTROOTFH, | |||
RENAME, | RENAME, | |||
RESTOREFH | RESTOREFH | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_WRONG_CRED</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_WRONG_CRED</td> | |||
<td align="left"> | ||||
CLOSE, | CLOSE, | |||
CREATE_SESSION, | CREATE_SESSION, | |||
DELEGPURGE, | DELEGPURGE, | |||
DELEGRETURN, | DELEGRETURN, | |||
DESTROY_CLIENTID, | DESTROY_CLIENTID, | |||
DESTROY_SESSION, | DESTROY_SESSION, | |||
FREE_STATEID, | FREE_STATEID, | |||
LAYOUTCOMMIT, | LAYOUTCOMMIT, | |||
LAYOUTRETURN, | LAYOUTRETURN, | |||
LOCK, | LOCK, | |||
LOCKT, | LOCKT, | |||
LOCKU, | LOCKU, | |||
OPEN_DOWNGRADE, | OPEN_DOWNGRADE, | |||
RECLAIM_COMPLETE | RECLAIM_COMPLETE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_WRONG_TYPE</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_WRONG_TYPE</td> | |||
<td align="left"> | ||||
CB_LAYOUTRECALL, | CB_LAYOUTRECALL, | |||
CB_PUSH_DELEG, | CB_PUSH_DELEG, | |||
COMMIT, | COMMIT, | |||
GETATTR, | GETATTR, | |||
LAYOUTGET, | LAYOUTGET, | |||
LAYOUTRETURN, | LAYOUTRETURN, | |||
LINK, | LINK, | |||
LOCK, | LOCK, | |||
LOCKT, | LOCKT, | |||
NVERIFY, | NVERIFY, | |||
OPEN, | OPEN, | |||
OPENATTR, | OPENATTR, | |||
READ, | READ, | |||
READLINK, | READLINK, | |||
RECLAIM_COMPLETE, | RECLAIM_COMPLETE, | |||
SETATTR, | SETATTR, | |||
VERIFY, | VERIFY, | |||
WANT_DELEGATION, | WANT_DELEGATION, | |||
WRITE | WRITE | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | ||||
<c>NFS4ERR_XDEV</c> | <tr> | |||
<c> | <td align="left">NFS4ERR_XDEV</td> | |||
<td align="left"> | ||||
LINK, | LINK, | |||
RENAME | RENAME | |||
</c> | </td> | |||
<c /> | </tr> | |||
<c /> | </tbody> | |||
</table> | ||||
</texttable> | </section> | |||
</section> | </section> | |||
<section anchor="nfsv41procedures" numbered="true" toc="default"> | ||||
</section> | <name>NFSv4.1 Procedures</name> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <t> | |||
$ --> | Both procedures, NULL and COMPOUND, <bcp14>MUST</bcp14> be implemented. | |||
<!-- Copyright (C) The IETF Trust (2007) --> | ||||
<!-- Copyright (C) The Internet Society (2006) --> | ||||
<section anchor="nfsv41procedures" title="NFSv4.1 Procedures"> | ||||
<t> | ||||
Both procedures, NULL and COMPOUND, MUST be implemented. | ||||
</t> | </t> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="PROC_NULL" numbered="true" toc="default"> | |||
$ --> | <name>Procedure 0: NULL - No Operation</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="PROC_NULL_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="PROC_NULL" title="Procedure 0: NULL - No Operation" > | <sourcecode type="xdr"><![CDATA[ | |||
void;]]></sourcecode> | ||||
<section toc="exclude" anchor="PROC_NULL_ARGUMENTS" title="ARGUMENTS"> | </section> | |||
<figure> | <section toc="exclude" anchor="PROC_NULL_RESULTS" numbered="true"> | |||
<artwork> | <name>RESULTS</name> | |||
void; | <sourcecode type="xdr"><![CDATA[ | |||
</artwork> | void;]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="PROC_NULL_DESCRIPTION" numbered="true"> | |||
<name>DESCRIPTION</name> | ||||
<section toc="exclude" anchor="PROC_NULL_RESULTS" title="RESULTS"> | <t> | |||
<figure> | ||||
<artwork> | ||||
void; | ||||
</artwork> | ||||
</figure> | ||||
</section> | ||||
<section toc="exclude" anchor="PROC_NULL_DESCRIPTION" title="DESCRIPTION"> | ||||
<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 SHOULD ensure that no | service request. Therefore, the server <bcp14>SHOULD</bcp14> ensure that no | |||
unnecessary work is done in servicing this procedure. | unnecessary work is done in servicing this procedure. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="PROC_NULL_ERRORS" title="ERRORS"> | <section toc="exclude" anchor="PROC_NULL_ERRORS" numbered="true"> | |||
<t> | <name>ERRORS</name> | |||
<t> | ||||
None. | None. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_COMPOUND" numbered="true" toc="default"> | |||
$ --> | <name>Procedure 1: COMPOUND - Compound Operations</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_COMPOUND_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_COMPOUND" title="Procedure 1: COMPOUND - Compound Operations | <sourcecode type="xdr"><![CDATA[ | |||
" > | ||||
<section toc="exclude" anchor="OP_COMPOUND_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
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 28681 ¶ | skipping to change at line 28980 ¶ | |||
OP_LAYOUTRETURN = 51, | OP_LAYOUTRETURN = 51, | |||
OP_SECINFO_NO_NAME = 52, | OP_SECINFO_NO_NAME = 52, | |||
OP_SEQUENCE = 53, | OP_SEQUENCE = 53, | |||
OP_SET_SSV = 54, | OP_SET_SSV = 54, | |||
OP_TEST_STATEID = 55, | OP_TEST_STATEID = 55, | |||
OP_WANT_DELEGATION = 56, | OP_WANT_DELEGATION = 56, | |||
OP_DESTROY_CLIENTID = 57, | OP_DESTROY_CLIENTID = 57, | |||
OP_RECLAIM_COMPLETE = 58, | OP_RECLAIM_COMPLETE = 58, | |||
OP_ILLEGAL = 10044 | OP_ILLEGAL = 10044 | |||
}; | }; | |||
</artwork> | ||||
</figure> | ||||
<figure> | ||||
<artwork> | ||||
union nfs_argop4 switch (nfs_opnum4 argop) { | union nfs_argop4 switch (nfs_opnum4 argop) { | |||
case OP_ACCESS: ACCESS4args opaccess; | case OP_ACCESS: ACCESS4args opaccess; | |||
case OP_CLOSE: CLOSE4args opclose; | case OP_CLOSE: CLOSE4args opclose; | |||
case OP_COMMIT: COMMIT4args opcommit; | case OP_COMMIT: COMMIT4args opcommit; | |||
case OP_CREATE: CREATE4args opcreate; | case OP_CREATE: CREATE4args opcreate; | |||
case OP_DELEGPURGE: DELEGPURGE4args opdelegpurge; | case OP_DELEGPURGE: DELEGPURGE4args opdelegpurge; | |||
case OP_DELEGRETURN: DELEGRETURN4args opdelegreturn; | case OP_DELEGRETURN: DELEGRETURN4args opdelegreturn; | |||
case OP_GETATTR: GETATTR4args opgetattr; | case OP_GETATTR: GETATTR4args opgetattr; | |||
case OP_GETFH: void; | case OP_GETFH: void; | |||
case OP_LINK: LINK4args oplink; | case OP_LINK: LINK4args oplink; | |||
skipping to change at line 28790 ¶ | skipping to change at line 29086 ¶ | |||
DESTROY_CLIENTID4args | DESTROY_CLIENTID4args | |||
opdestroy_clientid; | opdestroy_clientid; | |||
case OP_RECLAIM_COMPLETE: | case OP_RECLAIM_COMPLETE: | |||
RECLAIM_COMPLETE4args | RECLAIM_COMPLETE4args | |||
opreclaim_complete; | opreclaim_complete; | |||
/* Operations not new to NFSv4.1 */ | /* Operations not new to NFSv4.1 */ | |||
case OP_ILLEGAL: void; | case OP_ILLEGAL: void; | |||
}; | }; | |||
</artwork> | ||||
</figure> | ||||
<figure> | ||||
<artwork> | ||||
struct COMPOUND4args { | struct COMPOUND4args { | |||
utf8str_cs tag; | utf8str_cs tag; | |||
uint32_t minorversion; | uint32_t minorversion; | |||
nfs_argop4 argarray<>; | nfs_argop4 argarray<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
<section toc="exclude" anchor="OP_COMPOUND_RESULTS" numbered="true"> | ||||
</section> | <name>RESULTS</name> | |||
<sourcecode type="xdr"><![CDATA[ | ||||
<section toc="exclude" anchor="OP_COMPOUND_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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 28921 ¶ | skipping to change at line 29210 ¶ | |||
DESTROY_CLIENTID4res | DESTROY_CLIENTID4res | |||
opdestroy_clientid; | opdestroy_clientid; | |||
case OP_RECLAIM_COMPLETE: | case OP_RECLAIM_COMPLETE: | |||
RECLAIM_COMPLETE4res | RECLAIM_COMPLETE4res | |||
opreclaim_complete; | opreclaim_complete; | |||
/* Operations not new to NFSv4.1 */ | /* Operations not new to NFSv4.1 */ | |||
case OP_ILLEGAL: ILLEGAL4res opillegal; | case OP_ILLEGAL: ILLEGAL4res opillegal; | |||
}; | }; | |||
</artwork> | ||||
</figure> | ||||
<figure> | ||||
<artwork> | ||||
struct COMPOUND4res { | struct COMPOUND4res { | |||
nfsstat4 status; | nfsstat4 status; | |||
utf8str_cs tag; | utf8str_cs tag; | |||
nfs_resop4 resarray<>; | nfs_resop4 resarray<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
<section toc="exclude" anchor="OP_COMPOUND_DESCRIPTION" numbered="true"> | ||||
</section> | <name>DESCRIPTION</name> | |||
<t> | ||||
<section toc="exclude" anchor="OP_COMPOUND_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The COMPOUND procedure is used to combine one or more NFSv4 | The COMPOUND procedure is used to combine one or more NFSv4 | |||
operations into a | operations into a | |||
single RPC request. The server interprets each of the operations in | single RPC request. The server interprets each of the operations in | |||
turn. If an operation is executed by the server and the status of that | turn. If an operation is executed by the server and the status of that | |||
operation is NFS4_OK, then the next operation in the COMPOUND | operation is NFS4_OK, then the next operation in the COMPOUND | |||
procedure is executed. The server continues this process until there | procedure is executed. The server continues this process until there | |||
are no more operations to be executed or until one of the operations has a | are no more operations to be executed or until one of the operations has a | |||
status value other than NFS4_OK. | status value other than NFS4_OK. | |||
</t> | </t> | |||
<t> | <t> | |||
In the processing of the COMPOUND procedure, the server may find that | In the processing of the COMPOUND procedure, the server may find that | |||
it does not have the available resources to execute any or all of the | it does not have the available resources to execute any or all of the | |||
operations within the COMPOUND sequence. See | operations within the COMPOUND sequence. See | |||
<xref target="COMPOUND_Sizing_Issues" /> for a more detailed discussion. | <xref target="COMPOUND_Sizing_Issues" format="default"/> for a more detail | |||
</t> | ed discussion. | |||
<t> | </t> | |||
<t> | ||||
The server will generally choose between two methods of decoding the | The server will generally choose between two methods of decoding the | |||
client's request. The first would be the traditional one-pass XDR | client's request. The first would be the traditional one-pass XDR | |||
decode. If there is an XDR decoding error in this case, the RPC XDR | decode. If there is an XDR decoding error in this case, the RPC XDR | |||
decode error would be returned. The second method would be to make an | decode error would be returned. The second method would be to make an | |||
initial pass to decode the basic COMPOUND request and then to XDR | initial pass to decode the basic COMPOUND request and then to XDR | |||
decode the individual operations; the most interesting is the decode | decode the individual operations; the most interesting is the decode | |||
of attributes. In this case, the server may encounter an XDR decode | of attributes. In this case, the server may encounter an XDR decode | |||
error during the second pass. If it does, the server would return | error during the second pass. If it does, the server would return | |||
the error NFS4ERR_BADXDR to signify the decode error. | the error NFS4ERR_BADXDR to signify the decode error. | |||
</t> | </t> | |||
<t> | <t> | |||
The COMPOUND arguments contain a "minorversion" field. For NFSv4.1, | The COMPOUND arguments contain a "minorversion" field. For NFSv4.1, | |||
the value for this field is 1. If the server receives | the value for this field is 1. If the server receives | |||
a COMPOUND procedure with a minorversion field value that it does not | a COMPOUND procedure with a minorversion field value that it does not | |||
support, the server MUST return an error of | support, the server <bcp14>MUST</bcp14> return an error of | |||
NFS4ERR_MINOR_VERS_MISMATCH and a zero-length resultdata array. | NFS4ERR_MINOR_VERS_MISMATCH and a zero-length resultdata array. | |||
</t> | </t> | |||
<t> | <t> | |||
Contained within the COMPOUND results is a "status" field. If the | Contained within the COMPOUND results is a "status" field. If the | |||
results array length is non-zero, this status must be equivalent to | results array length is non-zero, this status must be equivalent to | |||
the status of the last operation that was executed within the COMPOUND | the status of the last operation that was executed within the COMPOUND | |||
procedure. Therefore, if an operation incurred an error then the | procedure. Therefore, if an operation incurred an error then the | |||
"status" value will be the same error value as is being returned for | "status" value will be the same error value as is being returned for | |||
the operation that failed. | the operation that failed. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that operations zero and one are not defined for the | Note that operations zero and one are not defined for the | |||
COMPOUND procedure. Operation 2 is not defined and is reserved for | COMPOUND procedure. Operation 2 is not defined and is reserved for | |||
future definition and use with minor versioning. If the server | future definition and use with minor versioning. If the server | |||
receives an operation array that contains operation 2 and the | receives an operation array that contains operation 2 and the | |||
minorversion field has a value of zero, an error of | minorversion field has a value of zero, an error of | |||
NFS4ERR_OP_ILLEGAL, as described in the next paragraph, is returned to | NFS4ERR_OP_ILLEGAL, as described in the next paragraph, is returned to | |||
the client. If an operation array contains an operation 2 and the | the client. If an operation array contains an operation 2 and the | |||
minorversion field is non-zero and the server does not support the | minorversion field is non-zero and the server does not support the | |||
minor version, the server returns an error of | minor version, the server returns an error of | |||
NFS4ERR_MINOR_VERS_MISMATCH. Therefore, the | NFS4ERR_MINOR_VERS_MISMATCH. Therefore, the | |||
NFS4ERR_MINOR_VERS_MISMATCH error takes precedence over all other | NFS4ERR_MINOR_VERS_MISMATCH error takes precedence over all other | |||
errors. | errors. | |||
</t> | </t> | |||
<t> | <t> | |||
It is possible that the server receives a request that contains an | It is possible that the server receives a request that contains an | |||
operation that is less than the first legal operation (OP_ACCESS) or | operation that is less than the first legal operation (OP_ACCESS) or | |||
greater than the last legal operation (OP_RELEASE_LOCKOWNER). In this | greater than the last legal operation (OP_RELEASE_LOCKOWNER). In this | |||
case, the server's response will encode the opcode OP_ILLEGAL rather | case, the server's response will encode the opcode OP_ILLEGAL rather | |||
than the illegal opcode of the request. The status field in the | than the illegal opcode of the request. The status field in the | |||
ILLEGAL return results will be set to NFS4ERR_OP_ILLEGAL. The COMPOUND | ILLEGAL return results will be set to NFS4ERR_OP_ILLEGAL. The COMPOUND | |||
procedure's return results will also be NFS4ERR_OP_ILLEGAL. | procedure's return results will also be NFS4ERR_OP_ILLEGAL. | |||
</t> | </t> | |||
<t> | <t> | |||
The definition of the "tag" in the request is left to the implementor. | The definition of the "tag" in the request is left to the implementor. | |||
It may be used to summarize the content of the Compound request for | It may be used to summarize the content of the Compound request for | |||
the benefit of packet-sniffers and engineers debugging | the benefit of packet-sniffers and engineers debugging | |||
implementations. However, the value of "tag" in the response SHOULD | implementations. However, the value of "tag" in the response <bcp14>SHOUL D</bcp14> | |||
be the same value as provided in the request. This applies to the tag | be the same value as provided in the request. This applies to the tag | |||
field of the CB_COMPOUND procedure as well. | field of the CB_COMPOUND procedure as well. | |||
</t> | </t> | |||
<section toc="exclude" anchor="current_filehandle_stateid" | <section toc="exclude" anchor="current_filehandle_stateid" numbered="t | |||
title="Current Filehandle and Stateid"> | rue"> | |||
<t> | <name>Current Filehandle and Stateid</name> | |||
<t> | ||||
The COMPOUND procedure offers a simple environment for the | The COMPOUND procedure offers a simple environment for the | |||
execution of the operations specified by the client. The first | execution of the operations specified by the client. The first | |||
two relate to the filehandle while the second two relate to the | two relate to the filehandle while the second two relate to the | |||
current stateid. | current stateid. | |||
</t> | </t> | |||
<section toc="exclude" anchor="current_filehandle" title="Current | <section toc="exclude" anchor="current_filehandle" numbered="true"> | |||
Filehandle"> | <name>Current Filehandle</name> | |||
<t> | <t> | |||
The current and saved filehandles are used throughout | The current and saved filehandles are used throughout | |||
the protocol. Most operations implicitly use | the protocol. Most operations implicitly use | |||
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> | |||
<t> | <figure anchor="curfh_example"> | |||
<figure anchor='curfh_example'> | <sourcecode type="nfsv4compound"><![CDATA[ | |||
<artwork> | ||||
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 | GETFH]]></sourcecode> | |||
</artwork> | </figure> | |||
</figure> | <t> | |||
</t> | In this example, the PUTFH (<xref target="OP_PUTFH" format="default"/>) op | |||
<t> | eration explicitly sets the current | |||
In this example, the PUTFH (<xref target="OP_PUTFH"/>) operation explicitl | ||||
y sets the current | ||||
filehandle value while the result of each LOOKUP operation sets | filehandle value while the result of each LOOKUP operation sets | |||
the current filehandle value to the resultant file system | the current filehandle value to the resultant file system | |||
object. Also, the client is able to insert GETATTR operations | object. Also, the client is able to insert GETATTR operations | |||
using the current filehandle as an argument. | using the current filehandle as an argument. | |||
</t> | </t> | |||
<t> | <t> | |||
The PUTROOTFH (<xref target="OP_PUTROOTFH"/>) and | The PUTROOTFH (<xref target="OP_PUTROOTFH" format="default"/>) and | |||
PUTPUBFH (<xref target="OP_PUTPUBFH"/>) operations also set the | PUTPUBFH (<xref target="OP_PUTPUBFH" format="default"/>) operations also | |||
set the | ||||
current filehandle. The above example would replace "PUTFH fh1" with | current filehandle. The above example would replace "PUTFH fh1" with | |||
PUTROOTFH or PUTPUBFH with no filehandle argument in order to | PUTROOTFH or PUTPUBFH with no filehandle argument in order to | |||
achieve the same effect (on the assumption that "compA" is directly | achieve the same effect (on the assumption that "compA" is directly | |||
below the root of the namespace). | below the root of the namespace). | |||
</t> | </t> | |||
<t> | <t> | |||
Along with the current filehandle, there is a saved filehandle. | Along with the current filehandle, there is a saved filehandle. | |||
While the current filehandle is set as the result of | While the current filehandle is set as the result of | |||
operations like LOOKUP, the saved filehandle must be set | operations like LOOKUP, the saved filehandle must be set | |||
directly with the use of the SAVEFH operation. The SAVEFH | directly with the use of the SAVEFH operation. The SAVEFH | |||
operation copies the current filehandle value to the saved | operation copies the current filehandle value to the saved | |||
value. The saved filehandle value is used in combination with | value. The saved filehandle value is used in combination with | |||
the current filehandle value for the LINK and RENAME | the current filehandle value for the LINK and RENAME | |||
operations. The RESTOREFH operation will copy the saved filehandle value to the current filehandle value; as a result, the | operations. The RESTOREFH operation will copy the saved filehandle value to the current filehandle value; as a result, the | |||
saved filehandle value may be used a sort of "scratch" area for | saved filehandle value may be used a sort of "scratch" area for | |||
the client's series of operations. | the client's series of operations. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="current_stateid" numbered="true"> | ||||
<section toc="exclude" anchor="current_stateid" title="Current Stateid"> | <name>Current Stateid</name> | |||
<t> | <t> | |||
With NFSv4.1, additions of a current stateid and a saved stateid | With NFSv4.1, additions of a current stateid and a saved stateid | |||
have been made to the COMPOUND processing environment; this | have been made to the COMPOUND processing environment; this | |||
allows for the passing of stateids between operations. There | allows for the passing of stateids between operations. There | |||
are no changes to the syntax of the protocol, only changes to | are no changes to the syntax of the protocol, only changes to | |||
the semantics of a few operations. | the semantics of a few operations. | |||
</t> | </t> | |||
<t> | <t> | |||
A "current stateid" is the stateid that is associated | A "current stateid" is the stateid that is associated | |||
with the current filehandle. The current stateid | with the current filehandle. The current stateid | |||
may only be changed by an operation that modifies | may only be changed by an operation that modifies | |||
the current filehandle or returns a stateid. If an | the current filehandle or returns a stateid. If an | |||
operation returns a stateid, it MUST set the current | operation returns a stateid, it <bcp14>MUST</bcp14> set the current | |||
stateid to the returned value. If an operation sets | stateid to the returned value. If an operation sets | |||
the current filehandle but does not return a stateid, | the current filehandle but does not return a stateid, | |||
the current stateid MUST be set to the all-zeros | the current stateid <bcp14>MUST</bcp14> be set to the all-zeros | |||
special stateid, i.e., (seqid, other) = (0, 0). | special stateid, i.e., (seqid, other) = (0, 0). | |||
If an operation uses a stateid as an argument but does | If an operation uses a stateid as an argument but does | |||
not return a stateid, the current stateid MUST NOT be | not return a stateid, the current stateid <bcp14>MUST NOT</bcp14> be | |||
changed. | changed. | |||
For example, PUTFH, PUTROOTFH, and PUTPUBFH | For example, PUTFH, PUTROOTFH, and PUTPUBFH | |||
will change the current server state from {ocfh, | will change the current server state from {ocfh, | |||
(osid)} to {cfh, (0, 0)}, while LOCK will change the current | (osid)} to {cfh, (0, 0)}, while LOCK will change the current | |||
state from {cfh, (osid} to {cfh, (nsid)}. Operations like | state from {cfh, (osid} to {cfh, (nsid)}. Operations like | |||
LOOKUP that transform a current filehandle and | LOOKUP that transform a current filehandle and | |||
component name into a new current filehandle will also | component name into a new current filehandle will also | |||
change the current state to {0, 0}. The SAVEFH | change the current state to {0, 0}. The SAVEFH | |||
and RESTOREFH operations will save and restore both | and RESTOREFH operations will save and restore both | |||
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"> | |||
<artwork> | <sourcecode type="nfsv4compound"><![CDATA[ | |||
PUTFH fh1 - -> {fh1, (0, 0)} | PUTFH fh1 - -> {fh1, (0, 0)} | |||
READ (sid1), 0, 1024 {fh1, (0, 0)} -> {fh1, (0, 0)} | READ (sid1), 0, 1024 {fh1, (0, 0)} -> {fh1, (0, 0)}]]></sourcecode> | |||
</artwork> | </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"> | |||
<artwork> | <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)} | CLOSE (1, 0) {fh2, (sid1)} -> {fh2, (sid2)}]]></sourcecode> | |||
</artwork> | </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"> | |||
<artwork> | <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)} | |||
READ (1, 0), 1024, 1024 {fh1, (sid3)} -> {fh1, (sid3)} | READ (1, 0), 1024, 1024 {fh1, (sid3)} -> {fh1, (sid3)}]]></sourcecode> | |||
</artwork> | </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 MUST return NFS4ERR_BAD_STATEID | the READ operation. The server <bcp14>MUST</bcp14> return NFS4ERR_BAD_STAT EID | |||
in the reply to the READ operation. | in the reply to the READ operation. | |||
</t> | </t> | |||
<figure anchor='csid_example4'> | <figure anchor="csid_example4"> | |||
<artwork> | <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 | READ (1, 0), 0, 1024 {fh1, (0, 0)} -> NFS4ERR_BAD_STATEID]]></sourcecod | |||
</artwork> | e> | |||
</figure> | </figure> | |||
</section> | ||||
</section> | </section> | |||
</section> | </section> | |||
</section> | <section toc="exclude" anchor="OP_COMPOUND_ERRORS" numbered="true"> | |||
<name>ERRORS</name> | ||||
<section toc="exclude" anchor="OP_COMPOUND_ERRORS" title="ERRORS"> | <t> | |||
<t> | ||||
COMPOUND will of course return every error that each operation on | COMPOUND will of course return every error that each operation on | |||
the fore channel can return (see <xref target="op_error_returns"/>). | the fore channel can return (see <xref target="op_error_returns" format="de fault"/>). | |||
However, if COMPOUND returns zero operations, obviously the error | However, if COMPOUND returns zero operations, obviously the error | |||
returned by COMPOUND has nothing to do with an error returned by | returned by COMPOUND has nothing to do with an error returned by | |||
an operation. The list of errors COMPOUND will return if it processes | an operation. The list of errors COMPOUND will return if it processes | |||
zero operations include: | zero operations include: | |||
</t> | </t> | |||
<texttable anchor="compounderrs"> | <table anchor="compounderrs" align="center"> | |||
<preamble>COMPOUND Error Returns</preamble> | <name>COMPOUND Error Returns</name> | |||
<ttcol align='left'>Error</ttcol> | <thead> | |||
<ttcol align='left'>Notes</ttcol> | <tr> | |||
<th align="left">Error</th> | ||||
<c>NFS4ERR_BADCHAR</c> <c>The tag argument has a character the replier | <th align="left">Notes</th> | |||
does not support. </c> | </tr> | |||
</thead> | ||||
<c>NFS4ERR_BADXDR</c> <c> </c> | <tbody> | |||
<tr> | ||||
<c>NFS4ERR_DELAY</c> <c> </c> | <td align="left">NFS4ERR_BADCHAR</td> | |||
<td align="left">The tag argument has a character the replier | ||||
<c>NFS4ERR_INVAL</c> <c>The tag argument is not in UTF-8 encoding.</c> | does not support. </td> | |||
</tr> | ||||
<c>NFS4ERR_MINOR_VERS_MISMATCH</c> <c> </c> | <tr> | |||
<td align="left">NFS4ERR_BADXDR</td> | ||||
<c>NFS4ERR_SERVERFAULT</c> <c> </c> | <td align="left"> </td> | |||
</tr> | ||||
<c>NFS4ERR_TOO_MANY_OPS</c> <c> </c> | <tr> | |||
<td align="left">NFS4ERR_DELAY</td> | ||||
<c>NFS4ERR_REP_TOO_BIG</c> <c> </c> | <td align="left"> </td> | |||
</tr> | ||||
<c>NFS4ERR_REP_TOO_BIG_TO_CACHE</c> <c> </c> | <tr> | |||
<td align="left">NFS4ERR_INVAL</td> | ||||
<c>NFS4ERR_REQ_TOO_BIG</c> <c> </c> | <td align="left">The tag argument is not in UTF-8 encoding.</td> | |||
</tr> | ||||
</texttable> | <tr> | |||
<td align="left">NFS4ERR_MINOR_VERS_MISMATCH</td> | ||||
</section> | <td align="left"> </td> | |||
</tr> | ||||
</section> | <tr> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <td align="left">NFS4ERR_SERVERFAULT</td> | |||
$ --> | <td align="left"> </td> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | </tr> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <tr> | |||
<td align="left">NFS4ERR_TOO_MANY_OPS</td> | ||||
<td align="left"> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_REP_TOO_BIG</td> | ||||
<td align="left"> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_REP_TOO_BIG_TO_CACHE</td> | ||||
<td align="left"> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_REQ_TOO_BIG</td> | ||||
<td align="left"> </td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
</section> | ||||
</section> | ||||
</section> | </section> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="operation_mandlist" numbered="true" toc="default"> | |||
$ --> | <name>Operations: <bcp14>REQUIRED</bcp14>, <bcp14>RECOMMENDED</bcp14>, or | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <bcp14>OPTIONAL</bcp14></name> | |||
<section anchor="operation_mandlist" | <t> | |||
title="Operations: REQUIRED, RECOMMENDED, or OPTIONAL"> | ||||
<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 REQUIRED, | protocol and the corresponding designation of <bcp14>REQUIRED</bcp14>, | |||
RECOMMENDED, and OPTIONAL to implement or MUST NOT implement. The | <bcp14>RECOMMENDED</bcp14>, and <bcp14>OPTIONAL</bcp14> to implement or <bcp | |||
designation of MUST NOT implement is reserved for those operations | 14>MUST NOT</bcp14> implement. The | |||
that were defined in NFSv4.0 and MUST NOT be implemented in NFSv4.1. | designation of <bcp14>MUST NOT</bcp14> implement is reserved for those opera | |||
</t> | tions | |||
<t> | that were defined in NFSv4.0 and <bcp14>MUST NOT</bcp14> be implemented in N | |||
For the most part, the REQUIRED, RECOMMENDED, or OPTIONAL designation for | FSv4.1. | |||
</t> | ||||
<t> | ||||
For the most part, the <bcp14>REQUIRED</bcp14>, <bcp14>RECOMMENDED</bcp14>, | ||||
or <bcp14>OPTIONAL</bcp14> designation for | ||||
operations sent by the client is for | operations sent by the client is for | |||
the server implementation. The client is generally required to | the server implementation. The client is generally required to | |||
implement the operations needed for the operating environment for | implement the operations needed for the operating environment for | |||
which it serves. For example, a read-only NFSv4.1 client would | which it serves. For example, a read-only NFSv4.1 client would | |||
have no need to implement the WRITE operation and is not required | have no need to implement the WRITE operation and is not required | |||
to do so. | to do so. | |||
</t> | </t> | |||
<t> | <t> | |||
The REQUIRED or OPTIONAL designation for | The <bcp14>REQUIRED</bcp14> or <bcp14>OPTIONAL</bcp14> designation for | |||
callback operations sent by the server is for both the client | callback operations sent by the server is for both the client | |||
and server. Generally, the client has the option of | and server. Generally, the client has the option of | |||
creating the backchannel and sending the operations on the | creating the backchannel and sending the operations on the | |||
fore channel that will be a catalyst for the server sending | fore channel that will be a catalyst for the server sending | |||
callback operations. A partial | callback operations. A partial | |||
exception is CB_RECALL_SLOT; the only way the client can | exception is CB_RECALL_SLOT; the only way the client can | |||
avoid supporting this operation is by not creating a backchannel. | avoid supporting this operation is by not creating a backchannel. | |||
</t> | </t> | |||
<t> | <t> | |||
Since this is a summary of the operations and their designation, | Since this is a summary of the operations and their designation, | |||
there are subtleties that are not presented here. Therefore, if | there are subtleties that are not presented here. Therefore, if | |||
there is a question of the requirements of implementation, the | there is a question of the requirements of implementation, the | |||
operation descriptions themselves must be consulted along with | operation descriptions themselves must be consulted along with | |||
other relevant explanatory text within this specification. | other relevant explanatory text within this specification. | |||
</t> | </t> | |||
<t> | <t> | |||
The abbreviations used in the second and third columns of the table | The abbreviations used in the second and third columns of the table | |||
are defined as follows. | are defined as follows. | |||
<list style="hanging"> | ||||
<t hangText="REQ"> | ||||
REQUIRED to implement | ||||
</t> | </t> | |||
<t hangText="REC"> | <dl newline="false" spacing="normal"> | |||
<dt>REQ</dt> | ||||
<dd> | ||||
<bcp14>REQUIRED</bcp14> to implement | ||||
</dd> | ||||
<dt>REC</dt> | ||||
<dd> | ||||
RECOMMEND to implement | RECOMMEND to implement | |||
</t> | </dd> | |||
<t hangText="OPT"> | <dt>OPT</dt> | |||
OPTIONAL to implement | <dd> | |||
</t> | <bcp14>OPTIONAL</bcp14> to implement | |||
<t hangText="MNI"> | </dd> | |||
MUST NOT implement | <dt>MNI</dt> | |||
</t> | <dd> | |||
</list> | <bcp14>MUST NOT</bcp14> implement | |||
</t> | </dd> | |||
</dl> | ||||
<t> For the NFSv4.1 features that are OPTIONAL, the operations that | <t> For the NFSv4.1 features that are <bcp14>OPTIONAL</bcp14>, the operati | |||
support those features are OPTIONAL, and the server would return | ons that | |||
support those features are <bcp14>OPTIONAL</bcp14>, and the server would ret | ||||
urn | ||||
NFS4ERR_NOTSUPP in response to the client's use of those | NFS4ERR_NOTSUPP in response to the client's use of those | |||
operations. If an OPTIONAL feature is supported, it is possible | operations. If an <bcp14>OPTIONAL</bcp14> feature is supported, it is possi | |||
that a set of operations related to the feature become REQUIRED | ble | |||
that a set of operations related to the feature become <bcp14>REQUIRED</bcp1 | ||||
4> | ||||
to implement. The third column of the table designates the | to implement. The third column of the table designates the | |||
feature(s) and if the operation is REQUIRED or OPTIONAL in the | feature(s) and if the operation is <bcp14>REQUIRED</bcp14> or <bcp14>OPTIONA L</bcp14> in the | |||
presence of support for the feature. | presence of support for the feature. | |||
</t> | </t> | |||
<t> | <t> | |||
The OPTIONAL features identified and their abbreviations are as | The <bcp14>OPTIONAL</bcp14> features identified and their abbreviations are | |||
as | ||||
follows: | follows: | |||
<list style="hanging"> | ||||
<t hangText="pNFS"> | ||||
Parallel NFS | ||||
</t> | </t> | |||
<t hangText="FDELG"> | <dl newline="false" spacing="normal"> | |||
<dt>pNFS</dt> | ||||
<dd> | ||||
Parallel NFS | ||||
</dd> | ||||
<dt>FDELG</dt> | ||||
<dd> | ||||
File Delegations | File Delegations | |||
</t> | </dd> | |||
<t hangText="DDELG"> | <dt>DDELG</dt> | |||
<dd> | ||||
Directory Delegations | Directory Delegations | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | <table align="center"> | |||
<texttable> | <name>Operations</name> | |||
<thead> | ||||
<preamble> Operations </preamble> | <tr> | |||
<th align="left">Operation</th> | ||||
<ttcol align='left' >Operation</ttcol> | <th align="left">REQ, REC, OPT, or MNI</th> | |||
<ttcol align='left' >REQ, REC, OPT, or MNI</ttcol> | <th align="left">Feature (REQ, REC, or OPT)</th> | |||
<ttcol align='left' >Feature (REQ, REC, or OPT)</ttcol> | <th align="left">Definition</th> | |||
<ttcol align='left' >Definition</ttcol> | </tr> | |||
</thead> | ||||
<c> ACCESS </c> | <tbody> | |||
<c>REQ</c> | <tr> | |||
<c></c> | <td align="left"> ACCESS </td> | |||
<c> <xref target="OP_ACCESS" /> </c> | <td align="left">REQ</td> | |||
<td align="left"/> | ||||
<c> BACKCHANNEL_CTL </c> | <td align="left"> | |||
<c>REQ</c> | <xref target="OP_ACCESS" format="default"/> </td> | |||
<c></c> | </tr> | |||
<c> <xref target="OP_BACKCHANNEL_CTL" /> </c> | <tr> | |||
<td align="left"> BACKCHANNEL_CTL </td> | ||||
<c> BIND_CONN_TO_SESSION</c> | <td align="left">REQ</td> | |||
<c>REQ</c> | <td align="left"/> | |||
<c></c> | <td align="left"> | |||
<c> <xref target="OP_BIND_CONN_TO_SESSION" /> </c> | <xref target="OP_BACKCHANNEL_CTL" format="default"/> </td> | |||
</tr> | ||||
<c> CLOSE </c> | <tr> | |||
<c>REQ</c> | <td align="left"> BIND_CONN_TO_SESSION</td> | |||
<c></c> | <td align="left">REQ</td> | |||
<c> <xref target="OP_CLOSE" /> </c> | <td align="left"/> | |||
<td align="left"> | ||||
<c> COMMIT </c> | <xref target="OP_BIND_CONN_TO_SESSION" format="default"/> </td> | |||
<c>REQ</c> | </tr> | |||
<c></c> | <tr> | |||
<c> <xref target="OP_COMMIT" /> </c> | <td align="left"> CLOSE </td> | |||
<td align="left">REQ</td> | ||||
<c> CREATE </c> | <td align="left"/> | |||
<c>REQ</c> | <td align="left"> | |||
<c></c> | <xref target="OP_CLOSE" format="default"/> </td> | |||
<c> <xref target="OP_CREATE" /> </c> | </tr> | |||
<tr> | ||||
<c> CREATE_SESSION </c> | <td align="left"> COMMIT </td> | |||
<c>REQ</c> | <td align="left">REQ</td> | |||
<c></c> | <td align="left"/> | |||
<c> <xref target="OP_CREATE_SESSION" /> </c> | <td align="left"> | |||
<xref target="OP_COMMIT" format="default"/> </td> | ||||
<c> DELEGPURGE </c> | </tr> | |||
<c>OPT</c> | <tr> | |||
<c>FDELG (REQ)</c> | <td align="left"> CREATE </td> | |||
<c> <xref target="OP_DELEGPURGE" /> </c> | <td align="left">REQ</td> | |||
<td align="left"/> | ||||
<c> DELEGRETURN </c> | <td align="left"> | |||
<c>OPT</c> | <xref target="OP_CREATE" format="default"/> </td> | |||
<c>FDELG, DDELG, pNFS (REQ)</c> | </tr> | |||
<c> <xref target="OP_DELEGRETURN" /> </c> | <tr> | |||
<td align="left"> CREATE_SESSION </td> | ||||
<c> DESTROY_CLIENTID </c> | <td align="left">REQ</td> | |||
<c>REQ</c> | <td align="left"/> | |||
<c></c> | <td align="left"> | |||
<c> <xref target="OP_DESTROY_CLIENTID" /> </c> | <xref target="OP_CREATE_SESSION" format="default"/> </td> | |||
</tr> | ||||
<c> DESTROY_SESSION </c> | <tr> | |||
<c>REQ</c> | <td align="left"> DELEGPURGE </td> | |||
<c></c> | <td align="left">OPT</td> | |||
<c> <xref target="OP_DESTROY_SESSION" /> </c> | <td align="left">FDELG (REQ)</td> | |||
<td align="left"> | ||||
<c> EXCHANGE_ID </c> | <xref target="OP_DELEGPURGE" format="default"/> </td> | |||
<c>REQ</c> | </tr> | |||
<c></c> | <tr> | |||
<c> <xref target="OP_EXCHANGE_ID" /> </c> | <td align="left"> DELEGRETURN </td> | |||
<td align="left">OPT</td> | ||||
<c> FREE_STATEID </c> | <td align="left">FDELG, DDELG, pNFS (REQ)</td> | |||
<c>REQ</c> | <td align="left"> | |||
<c></c> | <xref target="OP_DELEGRETURN" format="default"/> </td> | |||
<c> <xref target="OP_FREE_STATEID" /> </c> | </tr> | |||
<tr> | ||||
<c> GETATTR </c> | <td align="left"> DESTROY_CLIENTID </td> | |||
<c>REQ</c> | <td align="left">REQ</td> | |||
<c></c> | <td align="left"/> | |||
<c> <xref target="OP_GETATTR" /> </c> | <td align="left"> | |||
<xref target="OP_DESTROY_CLIENTID" format="default"/> </td> | ||||
<c> GETDEVICEINFO </c> | </tr> | |||
<c>OPT</c> | <tr> | |||
<c>pNFS (REQ)</c> | <td align="left"> DESTROY_SESSION </td> | |||
<c> <xref target="OP_GETDEVICEINFO" /> </c> | <td align="left">REQ</td> | |||
<td align="left"/> | ||||
<c> GETDEVICELIST</c> | <td align="left"> | |||
<c>OPT</c> | <xref target="OP_DESTROY_SESSION" format="default"/> </td> | |||
<c>pNFS (OPT)</c> | </tr> | |||
<c> <xref target="OP_GETDEVICELIST" /> </c> | <tr> | |||
<td align="left"> EXCHANGE_ID </td> | ||||
<c> GETFH </c> | <td align="left">REQ</td> | |||
<c>REQ</c> | <td align="left"/> | |||
<c></c> | <td align="left"> | |||
<c> <xref target="OP_GETFH" /> </c> | <xref target="OP_EXCHANGE_ID" format="default"/> </td> | |||
</tr> | ||||
<c> GET_DIR_DELEGATION </c> | <tr> | |||
<c>OPT</c> | <td align="left"> FREE_STATEID </td> | |||
<c>DDELG (REQ)</c> | <td align="left">REQ</td> | |||
<c> <xref target="OP_GET_DIR_DELEGATION" /> </c> | <td align="left"/> | |||
<td align="left"> | ||||
<c> LAYOUTCOMMIT </c> | <xref target="OP_FREE_STATEID" format="default"/> </td> | |||
<c>OPT</c> | </tr> | |||
<c>pNFS (REQ)</c> | <tr> | |||
<c> <xref target="OP_LAYOUTCOMMIT" /> </c> | <td align="left"> GETATTR </td> | |||
<td align="left">REQ</td> | ||||
<c> LAYOUTGET </c> | <td align="left"/> | |||
<c>OPT</c> | <td align="left"> | |||
<c>pNFS (REQ)</c> | <xref target="OP_GETATTR" format="default"/> </td> | |||
<c> <xref target="OP_LAYOUTGET" /> </c> | </tr> | |||
<tr> | ||||
<c> LAYOUTRETURN </c> | <td align="left"> GETDEVICEINFO </td> | |||
<c>OPT</c> | <td align="left">OPT</td> | |||
<c>pNFS (REQ)</c> | <td align="left">pNFS (REQ)</td> | |||
<c> <xref target="OP_LAYOUTRETURN" /> </c> | <td align="left"> | |||
<xref target="OP_GETDEVICEINFO" format="default"/> </td> | ||||
<c> LINK </c> | </tr> | |||
<c>OPT</c> | <tr> | |||
<c></c> | <td align="left"> GETDEVICELIST</td> | |||
<c> <xref target="OP_LINK" /> </c> | <td align="left">OPT</td> | |||
<td align="left">pNFS (OPT)</td> | ||||
<c> LOCK </c> | <td align="left"> | |||
<c>REQ</c> | <xref target="OP_GETDEVICELIST" format="default"/> </td> | |||
<c></c> | </tr> | |||
<c> <xref target="OP_LOCK" /> </c> | <tr> | |||
<td align="left"> GETFH </td> | ||||
<c> LOCKT </c> | <td align="left">REQ</td> | |||
<c>REQ</c> | <td align="left"/> | |||
<c></c> | <td align="left"> | |||
<c> <xref target="OP_LOCKT" /> </c> | <xref target="OP_GETFH" format="default"/> </td> | |||
</tr> | ||||
<c> LOCKU </c> | <tr> | |||
<c>REQ</c> | <td align="left"> GET_DIR_DELEGATION </td> | |||
<c></c> | <td align="left">OPT</td> | |||
<c> <xref target="OP_LOCKU" /> </c> | <td align="left">DDELG (REQ)</td> | |||
<td align="left"> | ||||
<c> LOOKUP </c> | <xref target="OP_GET_DIR_DELEGATION" format="default"/> </td> | |||
<c>REQ</c> | </tr> | |||
<c></c> | <tr> | |||
<c> <xref target="OP_LOOKUP" /> </c> | <td align="left"> LAYOUTCOMMIT </td> | |||
<td align="left">OPT</td> | ||||
<c> LOOKUPP </c> | <td align="left">pNFS (REQ)</td> | |||
<c>REQ</c> | <td align="left"> | |||
<c></c> | <xref target="OP_LAYOUTCOMMIT" format="default"/> </td> | |||
<c> <xref target="OP_LOOKUPP" /> </c> | </tr> | |||
<tr> | ||||
<c> NVERIFY </c> | <td align="left"> LAYOUTGET </td> | |||
<c>REQ</c> | <td align="left">OPT</td> | |||
<c></c> | <td align="left">pNFS (REQ)</td> | |||
<c> <xref target="OP_NVERIFY" /> </c> | <td align="left"> | |||
<xref target="OP_LAYOUTGET" format="default"/> </td> | ||||
<c> OPEN </c> | </tr> | |||
<c>REQ</c> | <tr> | |||
<c></c> | <td align="left"> LAYOUTRETURN </td> | |||
<c> <xref target="OP_OPEN" /> </c> | <td align="left">OPT</td> | |||
<td align="left">pNFS (REQ)</td> | ||||
<c> OPENATTR </c> | <td align="left"> | |||
<c>OPT</c> | <xref target="OP_LAYOUTRETURN" format="default"/> </td> | |||
<c></c> | </tr> | |||
<c> <xref target="OP_OPENATTR" /> </c> | <tr> | |||
<td align="left"> LINK </td> | ||||
<c> OPEN_CONFIRM </c> | <td align="left">OPT</td> | |||
<c>MNI</c> | <td align="left"/> | |||
<c></c> | <td align="left"> | |||
<c> N/A </c> | <xref target="OP_LINK" format="default"/> </td> | |||
</tr> | ||||
<c> OPEN_DOWNGRADE </c> | <tr> | |||
<c>REQ</c> | <td align="left"> LOCK </td> | |||
<c></c> | <td align="left">REQ</td> | |||
<c> <xref target="OP_OPEN_DOWNGRADE" /> </c> | <td align="left"/> | |||
<td align="left"> | ||||
<c> PUTFH </c> | <xref target="OP_LOCK" format="default"/> </td> | |||
<c>REQ</c> | </tr> | |||
<c></c> | <tr> | |||
<c> <xref target="OP_PUTFH" /> </c> | <td align="left"> LOCKT </td> | |||
<td align="left">REQ</td> | ||||
<c> PUTPUBFH </c> | <td align="left"/> | |||
<c>REQ</c> | <td align="left"> | |||
<c></c> | <xref target="OP_LOCKT" format="default"/> </td> | |||
<c> <xref target="OP_PUTPUBFH" /> </c> | </tr> | |||
<tr> | ||||
<c> PUTROOTFH </c> | <td align="left"> LOCKU </td> | |||
<c>REQ</c> | <td align="left">REQ</td> | |||
<c></c> | <td align="left"/> | |||
<c> <xref target="OP_PUTROOTFH" /> </c> | <td align="left"> | |||
<xref target="OP_LOCKU" format="default"/> </td> | ||||
<c> READ </c> | </tr> | |||
<c>REQ</c> | <tr> | |||
<c></c> | <td align="left"> LOOKUP </td> | |||
<c> <xref target="OP_READ" /> </c> | <td align="left">REQ</td> | |||
<td align="left"/> | ||||
<c> READDIR </c> | <td align="left"> | |||
<c>REQ</c> | <xref target="OP_LOOKUP" format="default"/> </td> | |||
<c></c> | </tr> | |||
<c> <xref target="OP_READDIR" /> </c> | <tr> | |||
<td align="left"> LOOKUPP </td> | ||||
<c> READLINK </c> | <td align="left">REQ</td> | |||
<c>OPT</c> | <td align="left"/> | |||
<c></c> | <td align="left"> | |||
<c> <xref target="OP_READLINK" /> </c> | <xref target="OP_LOOKUPP" format="default"/> </td> | |||
</tr> | ||||
<c> RECLAIM_COMPLETE </c> | <tr> | |||
<c>REQ</c> | <td align="left"> NVERIFY </td> | |||
<c></c> | <td align="left">REQ</td> | |||
<c> <xref target="OP_RECLAIM_COMPLETE" /> </c> | <td align="left"/> | |||
<td align="left"> | ||||
<c> RELEASE_LOCKOWNER</c> | <xref target="OP_NVERIFY" format="default"/> </td> | |||
<c>MNI</c> | </tr> | |||
<c></c> | <tr> | |||
<c> N/A </c> | <td align="left"> OPEN </td> | |||
<td align="left">REQ</td> | ||||
<c> REMOVE </c> | <td align="left"/> | |||
<c>REQ</c> | <td align="left"> | |||
<c></c> | <xref target="OP_OPEN" format="default"/> </td> | |||
<c> <xref target="OP_REMOVE" /> </c> | </tr> | |||
<tr> | ||||
<c> RENAME </c> | <td align="left"> OPENATTR </td> | |||
<c>REQ</c> | <td align="left">OPT</td> | |||
<c></c> | <td align="left"/> | |||
<c> <xref target="OP_RENAME" /> </c> | <td align="left"> | |||
<xref target="OP_OPENATTR" format="default"/> </td> | ||||
<c> RENEW </c> | </tr> | |||
<c>MNI</c> | <tr> | |||
<c></c> | <td align="left"> OPEN_CONFIRM </td> | |||
<c> N/A </c> | <td align="left">MNI</td> | |||
<td align="left"/> | ||||
<c> RESTOREFH </c> | <td align="left"> N/A </td> | |||
<c>REQ</c> | </tr> | |||
<c></c> | <tr> | |||
<c> <xref target="OP_RESTOREFH" /> </c> | <td align="left"> OPEN_DOWNGRADE </td> | |||
<td align="left">REQ</td> | ||||
<c> SAVEFH </c> | <td align="left"/> | |||
<c>REQ</c> | <td align="left"> | |||
<c></c> | <xref target="OP_OPEN_DOWNGRADE" format="default"/> </td> | |||
<c> <xref target="OP_SAVEFH" /> </c> | </tr> | |||
<tr> | ||||
<c> SECINFO </c> | <td align="left"> PUTFH </td> | |||
<c>REQ</c> | <td align="left">REQ</td> | |||
<c></c> | <td align="left"/> | |||
<c> <xref target="OP_SECINFO" /> </c> | <td align="left"> | |||
<xref target="OP_PUTFH" format="default"/> </td> | ||||
<c> SECINFO_NO_NAME </c> | </tr> | |||
<c>REC</c> | <tr> | |||
<c>pNFS file layout (REQ)</c> | <td align="left"> PUTPUBFH </td> | |||
<c> <xref target="OP_SECINFO_NO_NAME" />, | <td align="left">REQ</td> | |||
<xref target="file_security_considerations"/> | <td align="left"/> | |||
</c> | <td align="left"> | |||
<xref target="OP_PUTPUBFH" format="default"/> </td> | ||||
<c> SEQUENCE </c> | </tr> | |||
<c>REQ</c> | <tr> | |||
<c></c> | <td align="left"> PUTROOTFH </td> | |||
<c> <xref target="OP_SEQUENCE" /> </c> | <td align="left">REQ</td> | |||
<td align="left"/> | ||||
<c> SETATTR </c> | <td align="left"> | |||
<c>REQ</c> | <xref target="OP_PUTROOTFH" format="default"/> </td> | |||
<c></c> | </tr> | |||
<c> <xref target="OP_SETATTR" /> </c> | <tr> | |||
<td align="left"> READ </td> | ||||
<c> SETCLIENTID</c> | <td align="left">REQ</td> | |||
<c>MNI</c> | <td align="left"/> | |||
<c></c> | <td align="left"> | |||
<c> N/A </c> | <xref target="OP_READ" format="default"/> </td> | |||
</tr> | ||||
<c> SETCLIENTID_CONFIRM</c> | <tr> | |||
<c>MNI</c> | <td align="left"> READDIR </td> | |||
<c></c> | <td align="left">REQ</td> | |||
<c> N/A </c> | <td align="left"/> | |||
<td align="left"> | ||||
<c> SET_SSV</c> | <xref target="OP_READDIR" format="default"/> </td> | |||
<c>REQ</c> | </tr> | |||
<c></c> | <tr> | |||
<c> <xref target="OP_SET_SSV" /> </c> | <td align="left"> READLINK </td> | |||
<td align="left">OPT</td> | ||||
<c> TEST_STATEID </c> | <td align="left"/> | |||
<c>REQ</c> | <td align="left"> | |||
<c></c> | <xref target="OP_READLINK" format="default"/> </td> | |||
<c> <xref target="OP_TEST_STATEID" /> </c> | </tr> | |||
<tr> | ||||
<c> VERIFY </c> | <td align="left"> RECLAIM_COMPLETE </td> | |||
<c>REQ</c> | <td align="left">REQ</td> | |||
<c></c> | <td align="left"/> | |||
<c> <xref target="OP_VERIFY" /> </c> | <td align="left"> | |||
<xref target="OP_RECLAIM_COMPLETE" format="default"/> </td> | ||||
<c> WANT_DELEGATION</c> | </tr> | |||
<c>OPT</c> | <tr> | |||
<c>FDELG (OPT)</c> | <td align="left"> RELEASE_LOCKOWNER</td> | |||
<c> <xref target="OP_WANT_DELEGATION" /> </c> | <td align="left">MNI</td> | |||
<td align="left"/> | ||||
<c> WRITE </c> | <td align="left"> N/A </td> | |||
<c>REQ</c> | </tr> | |||
<c></c> | <tr> | |||
<c> <xref target="OP_WRITE" /> </c> | <td align="left"> REMOVE </td> | |||
<td align="left">REQ</td> | ||||
</texttable> | <td align="left"/> | |||
<td align="left"> | ||||
<texttable> | <xref target="OP_REMOVE" format="default"/> </td> | |||
</tr> | ||||
<preamble> Callback Operations </preamble> | <tr> | |||
<ttcol align='left' >Operation</ttcol> | <td align="left"> RENAME </td> | |||
<ttcol align='left' >REQ, REC, OPT, or MNI</ttcol> | <td align="left">REQ</td> | |||
<ttcol align='left' >Feature (REQ, REC, or OPT)</ttcol> | <td align="left"/> | |||
<ttcol align='left' >Definition</ttcol> | <td align="left"> | |||
<xref target="OP_RENAME" format="default"/> </td> | ||||
<c> CB_GETATTR </c> | </tr> | |||
<c>OPT</c> | <tr> | |||
<c>FDELG (REQ)</c> | <td align="left"> RENEW </td> | |||
<c> <xref target="OP_CB_GETATTR" /> </c> | <td align="left">MNI</td> | |||
<td align="left"/> | ||||
<c> CB_LAYOUTRECALL </c> | <td align="left"> N/A </td> | |||
<c>OPT</c> | </tr> | |||
<c>pNFS (REQ)</c> | <tr> | |||
<c> <xref target="OP_CB_LAYOUTRECALL" /> </c> | <td align="left"> RESTOREFH </td> | |||
<td align="left">REQ</td> | ||||
<c> CB_NOTIFY </c> | <td align="left"/> | |||
<c>OPT</c> | <td align="left"> | |||
<c>DDELG (REQ)</c> | <xref target="OP_RESTOREFH" format="default"/> </td> | |||
<c> <xref target="OP_CB_NOTIFY" /> </c> | </tr> | |||
<tr> | ||||
<c> CB_NOTIFY_DEVICEID </c> | <td align="left"> SAVEFH </td> | |||
<c>OPT</c> | <td align="left">REQ</td> | |||
<c>pNFS (OPT)</c> | <td align="left"/> | |||
<c> <xref target="OP_CB_NOTIFY_DEVICEID" /> </c> | <td align="left"> | |||
<xref target="OP_SAVEFH" format="default"/> </td> | ||||
<c> CB_NOTIFY_LOCK </c> | </tr> | |||
<c>OPT</c> | <tr> | |||
<c></c> | <td align="left"> SECINFO </td> | |||
<c> <xref target="OP_CB_NOTIFY_LOCK" /> </c> | <td align="left">REQ</td> | |||
<td align="left"/> | ||||
<c> CB_PUSH_DELEG </c> | <td align="left"> | |||
<c>OPT</c> | <xref target="OP_SECINFO" format="default"/> </td> | |||
<c>FDELG (OPT)</c> | </tr> | |||
<c> <xref target="OP_CB_PUSH_DELEG" /> </c> | <tr> | |||
<td align="left"> SECINFO_NO_NAME </td> | ||||
<c> CB_RECALL </c> | <td align="left">REC</td> | |||
<c>OPT</c> | <td align="left">pNFS file layout (REQ)</td> | |||
<c>FDELG, DDELG, pNFS (REQ)</c> | <td align="left"> | |||
<c> <xref target="OP_CB_RECALL" /> </c> | <xref target="OP_SECINFO_NO_NAME" format="default"/>, | |||
<xref target="file_security_considerations" format="default"/> | ||||
<c> CB_RECALL_ANY </c> | </td> | |||
<c>OPT</c> | </tr> | |||
<c>FDELG, DDELG, pNFS (REQ)</c> | <tr> | |||
<c> <xref target="OP_CB_RECALL_ANY" /> </c> | <td align="left"> SEQUENCE </td> | |||
<td align="left">REQ</td> | ||||
<c> CB_RECALL_SLOT </c> | <td align="left"/> | |||
<c>REQ</c> | <td align="left"> | |||
<c></c> | <xref target="OP_SEQUENCE" format="default"/> </td> | |||
<c> <xref target="OP_CB_RECALL_SLOT" /> </c> | </tr> | |||
<tr> | ||||
<c> CB_RECALLABLE_OBJ_AVAIL </c> | <td align="left"> SETATTR </td> | |||
<c>OPT</c> | <td align="left">REQ</td> | |||
<c>DDELG, pNFS (REQ)</c> | <td align="left"/> | |||
<c> <xref target="OP_CB_RECALLABLE_OBJ_AVAIL" /> </c> | <td align="left"> | |||
<xref target="OP_SETATTR" format="default"/> </td> | ||||
<c> CB_SEQUENCE </c> | </tr> | |||
<c>OPT</c> | <tr> | |||
<c>FDELG, DDELG, pNFS (REQ)</c> | <td align="left"> SETCLIENTID</td> | |||
<c> <xref target="OP_CB_SEQUENCE" /> </c> | <td align="left">MNI</td> | |||
<td align="left"/> | ||||
<c> CB_WANTS_CANCELLED </c> | <td align="left"> N/A </td> | |||
<c>OPT</c> | </tr> | |||
<c>FDELG, DDELG, pNFS (REQ)</c> | <tr> | |||
<c> <xref target="OP_CB_WANTS_CANCELLED" /> </c> | <td align="left"> SETCLIENTID_CONFIRM</td> | |||
<td align="left">MNI</td> | ||||
</texttable> | <td align="left"/> | |||
</section> | <td align="left"> N/A </td> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | </tr> | |||
$ --> | <tr> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <td align="left"> SET_SSV</td> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <td align="left">REQ</td> | |||
<section anchor="nfsv41operations" title="NFSv4.1 Operations"> | <td align="left"/> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <td align="left"> | |||
$ --> | <xref target="OP_SET_SSV" format="default"/> </td> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | </tr> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <tr> | |||
<section anchor="OP_ACCESS" title="Operation 3: ACCESS - Check Access Rights" > | <td align="left"> TEST_STATEID </td> | |||
<td align="left">REQ</td> | ||||
<section toc="exclude" anchor="OP_ACCESS_ARGUMENTS" title="ARGUMENTS"> | <td align="left"/> | |||
<figure> | <td align="left"> | |||
<artwork> | <xref target="OP_TEST_STATEID" format="default"/> </td> | |||
</tr> | ||||
<tr> | ||||
<td align="left"> VERIFY </td> | ||||
<td align="left">REQ</td> | ||||
<td align="left"/> | ||||
<td align="left"> | ||||
<xref target="OP_VERIFY" format="default"/> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"> WANT_DELEGATION</td> | ||||
<td align="left">OPT</td> | ||||
<td align="left">FDELG (OPT)</td> | ||||
<td align="left"> | ||||
<xref target="OP_WANT_DELEGATION" format="default"/> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"> WRITE </td> | ||||
<td align="left">REQ</td> | ||||
<td align="left"/> | ||||
<td align="left"> | ||||
<xref target="OP_WRITE" format="default"/> </td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
<table align="center"> | ||||
<name>Callback Operations</name> | ||||
<thead> | ||||
<tr> | ||||
<th align="left">Operation</th> | ||||
<th align="left">REQ, REC, OPT, or MNI</th> | ||||
<th align="left">Feature (REQ, REC, or OPT)</th> | ||||
<th align="left">Definition</th> | ||||
</tr> | ||||
</thead> | ||||
<tbody> | ||||
<tr> | ||||
<td align="left"> CB_GETATTR </td> | ||||
<td align="left">OPT</td> | ||||
<td align="left">FDELG (REQ)</td> | ||||
<td align="left"> | ||||
<xref target="OP_CB_GETATTR" format="default"/> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"> CB_LAYOUTRECALL </td> | ||||
<td align="left">OPT</td> | ||||
<td align="left">pNFS (REQ)</td> | ||||
<td align="left"> | ||||
<xref target="OP_CB_LAYOUTRECALL" format="default"/> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"> CB_NOTIFY </td> | ||||
<td align="left">OPT</td> | ||||
<td align="left">DDELG (REQ)</td> | ||||
<td align="left"> | ||||
<xref target="OP_CB_NOTIFY" format="default"/> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"> CB_NOTIFY_DEVICEID </td> | ||||
<td align="left">OPT</td> | ||||
<td align="left">pNFS (OPT)</td> | ||||
<td align="left"> | ||||
<xref target="OP_CB_NOTIFY_DEVICEID" format="default"/> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"> CB_NOTIFY_LOCK </td> | ||||
<td align="left">OPT</td> | ||||
<td align="left"/> | ||||
<td align="left"> | ||||
<xref target="OP_CB_NOTIFY_LOCK" format="default"/> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"> CB_PUSH_DELEG </td> | ||||
<td align="left">OPT</td> | ||||
<td align="left">FDELG (OPT)</td> | ||||
<td align="left"> | ||||
<xref target="OP_CB_PUSH_DELEG" format="default"/> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"> CB_RECALL </td> | ||||
<td align="left">OPT</td> | ||||
<td align="left">FDELG, DDELG, pNFS (REQ)</td> | ||||
<td align="left"> | ||||
<xref target="OP_CB_RECALL" format="default"/> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"> CB_RECALL_ANY </td> | ||||
<td align="left">OPT</td> | ||||
<td align="left">FDELG, DDELG, pNFS (REQ)</td> | ||||
<td align="left"> | ||||
<xref target="OP_CB_RECALL_ANY" format="default"/> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"> CB_RECALL_SLOT </td> | ||||
<td align="left">REQ</td> | ||||
<td align="left"/> | ||||
<td align="left"> | ||||
<xref target="OP_CB_RECALL_SLOT" format="default"/> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"> CB_RECALLABLE_OBJ_AVAIL </td> | ||||
<td align="left">OPT</td> | ||||
<td align="left">DDELG, pNFS (REQ)</td> | ||||
<td align="left"> | ||||
<xref target="OP_CB_RECALLABLE_OBJ_AVAIL" format="default"/> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"> CB_SEQUENCE </td> | ||||
<td align="left">OPT</td> | ||||
<td align="left">FDELG, DDELG, pNFS (REQ)</td> | ||||
<td align="left"> | ||||
<xref target="OP_CB_SEQUENCE" format="default"/> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left"> CB_WANTS_CANCELLED </td> | ||||
<td align="left">OPT</td> | ||||
<td align="left">FDELG, DDELG, pNFS (REQ)</td> | ||||
<td align="left"> | ||||
<xref target="OP_CB_WANTS_CANCELLED" format="default"/> </td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
</section> | ||||
<section anchor="nfsv41operations" numbered="true" toc="default"> | ||||
<name>NFSv4.1 Operations</name> | ||||
<section anchor="OP_ACCESS" numbered="true" toc="default"> | ||||
<name>Operation 3: ACCESS - Check Access Rights</name> | ||||
<section toc="exclude" anchor="OP_ACCESS_ARGUMENTS" numbered="true"> | ||||
<name>ARGUMENTS</name> | ||||
<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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_ACCESS_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_ACCESS_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_ACCESS_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_ACCESS_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
ACCESS determines the access rights that a user, as identified by the | ACCESS determines the access rights that a user, as identified by the | |||
credentials in the RPC request, has with respect to the file system | credentials in the RPC request, has with respect to the file system | |||
object specified by the current filehandle. The client encodes the | object specified by the current filehandle. The client encodes the | |||
set of access rights that are to be checked in the bit mask "access". | set of access rights that are to be checked in the bit mask "access". | |||
The server checks the permissions encoded in the bit mask. If a | The server checks the permissions encoded in the bit mask. If a | |||
status of NFS4_OK is returned, two bit masks are included in the | status of NFS4_OK is returned, two bit masks are included in the | |||
response. The first, "supported", represents the access rights for | response. The first, "supported", represents the access rights for | |||
which the server can verify reliably. The second, "access", | which the server can verify reliably. The second, "access", | |||
represents the access rights available to the user for the filehandle | represents the access rights available to the user for the filehandle | |||
provided. On success, the current filehandle retains its value. | provided. On success, the current filehandle retains its value. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that the reply's supported and access fields MUST NOT | Note that the reply's supported and access fields <bcp14>MUST NOT</bcp14> | |||
contain more values than originally set in the request's | contain more values than originally set in the request's | |||
access field. For example, if the client sends an ACCESS | access field. For example, if the client sends an ACCESS | |||
operation with just the ACCESS4_READ value set and the | operation with just the ACCESS4_READ value set and the | |||
server supports this value, the server MUST NOT set more | server supports this value, the server <bcp14>MUST NOT</bcp14> set more | |||
than ACCESS4_READ in the supported field even if it could | than ACCESS4_READ in the supported field even if it could | |||
have reliably checked other values. | have reliably checked other values. | |||
</t> | </t> | |||
<t> | <t> | |||
The reply's access field MUST NOT contain more values than the | The reply's access field <bcp14>MUST NOT</bcp14> contain more values than t | |||
he | ||||
supported field. | supported field. | |||
</t> | </t> | |||
<t> | <t> | |||
The results of this operation are necessarily advisory in nature. A | The results of this operation are necessarily advisory in nature. A | |||
return status of NFS4_OK and the appropriate bit set in the bit mask | return status of NFS4_OK and the appropriate bit set in the bit mask | |||
do not imply that such access will be allowed to the file system | do not imply that such access will be allowed to the file system | |||
object in the future. This is because access rights can be revoked by | object in the future. This is because access rights can be revoked by | |||
the server at any time. | the server at any time. | |||
</t> | </t> | |||
<t> | <t> | |||
The following access permissions may be requested: | The following access permissions may be requested: | |||
<list style="hanging"> | ||||
<t hangText="ACCESS4_READ"> | ||||
Read data from file or read a directory. | ||||
</t> | </t> | |||
<t hangText="ACCESS4_LOOKUP"> | <dl newline="false" spacing="normal"> | |||
<dt>ACCESS4_READ</dt> | ||||
<dd> | ||||
Read data from file or read a directory. | ||||
</dd> | ||||
<dt>ACCESS4_LOOKUP</dt> | ||||
<dd> | ||||
Look up a name in a directory (no meaning for non-directory objects). | Look up a name in a directory (no meaning for non-directory objects). | |||
</t> | </dd> | |||
<t hangText="ACCESS4_MODIFY"> | <dt>ACCESS4_MODIFY</dt> | |||
<dd> | ||||
Rewrite existing file data or modify existing directory entries. | Rewrite existing file data or modify existing directory entries. | |||
</t> | </dd> | |||
<t hangText="ACCESS4_EXTEND"> | <dt>ACCESS4_EXTEND</dt> | |||
<dd> | ||||
Write new data or add directory entries. | Write new data or add directory entries. | |||
</t> | </dd> | |||
<t hangText="ACCESS4_DELETE"> | <dt>ACCESS4_DELETE</dt> | |||
<dd> | ||||
Delete an existing directory entry. | Delete an existing directory entry. | |||
</t> | </dd> | |||
<t hangText="ACCESS4_EXECUTE"> | <dt>ACCESS4_EXECUTE</dt> | |||
<dd> | ||||
Execute a regular file (no meaning for a directory). | Execute a regular file (no meaning for a directory). | |||
</t> | </dd> | |||
</list> | </dl> | |||
<t> | ||||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
<t> | <t> | |||
ACCESS4_EXECUTE is a challenging semantic to implement because | ACCESS4_EXECUTE is a challenging semantic to implement because | |||
NFS provides remote file access, not remote | NFS provides remote file access, not remote | |||
execution. This leads to the following: | execution. This leads to the following: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Whether or not a regular file is executable ought to be | Whether or not a regular file is executable ought to be | |||
the responsibility of the NFS client and not the server. And yet | the responsibility of the NFS client and not the server. And yet | |||
the ACCESS operation is specified to seemingly require a server to | the ACCESS operation is specified to seemingly require a server to | |||
own that responsibility. | own that responsibility. | |||
</t> | </li> | |||
<t> | <li> | |||
When a client executes a regular file, it has to | When a client executes a regular file, it has to | |||
read the file from the server. Strictly speaking, | read the file from the server. Strictly speaking, | |||
the server should not allow the client to read a file | the server should not allow the client to read a file | |||
being executed unless the user has read permissions | being executed unless the user has read permissions | |||
on the file. Requiring | on the file. Requiring | |||
explicit read permissions on executable files in order to | explicit read permissions on executable files in order to | |||
access them over NFS is not going to be acceptable to | access them over NFS is not going to be acceptable to | |||
some users and storage administrators. Historically, NFS servers have allow ed | some users and storage administrators. Historically, NFS servers have allow ed | |||
a user to READ a file if the user has execute access | a user to READ a file if the user has execute access | |||
to the file. | to the file. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | As a practical example, the UNIX specification <xref target="access_api" form | |||
As a practical example, the UNIX specification <xref | at="default"/> states that an implementation | |||
target="access_api"/> states that an implementation | ||||
claiming conformance to UNIX may indicate in the | claiming conformance to UNIX may indicate in the | |||
access() programming interface's result that a | access() programming interface's result that a | |||
privileged user has execute rights, even if no | privileged user has execute rights, even if no | |||
execute permission bits are set on the regular file's | execute permission bits are set on the regular file's | |||
attributes. It is possible to claim conformance | attributes. It is possible to claim conformance | |||
to the UNIX specification and instead not indicate | to the UNIX specification and instead not indicate | |||
execute rights in that situation, which is true for | execute rights in that situation, which is true for | |||
some operating environments. Suppose the operating | some operating environments. Suppose the operating | |||
environments of the client and server are implementing | environments of the client and server are implementing | |||
the access() semantics for privileged users differently, | the access() semantics for privileged users differently, | |||
and the ACCESS operation implementations of the client | and the ACCESS operation implementations of the client | |||
and server follow their respective access() semantics. | and server follow their respective access() semantics. | |||
This can cause undesired behavior: | This can cause undesired behavior: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Suppose the client's access() interface returns X_OK | Suppose the client's access() interface returns X_OK | |||
if the user is privileged and no execute permission | if the user is privileged and no execute permission | |||
bits are set on the regular file's attribute, and the | bits are set on the regular file's attribute, and the | |||
server's access() interface does not return X_OK in | server's access() interface does not return X_OK in | |||
that situation. Then the client will be unable to | that situation. Then the client will be unable to | |||
execute files stored on the NFS server that could be | execute files stored on the NFS server that could be | |||
executed if stored on a non-NFS file system. | executed if stored on a non-NFS file system. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
Suppose the client's access() interface does | Suppose the client's access() interface does | |||
not return X_OK if the user is privileged, and no | not return X_OK if the user is privileged, and no | |||
execute permission bits are set on the regular file's | execute permission bits are set on the regular file's | |||
attribute, and the server's access() interface does | attribute, and the server's access() interface does | |||
return X_OK in that situation. Then: | return X_OK in that situation. Then: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The client will be able to execute files stored on | The client will be able to execute files stored on | |||
the NFS server that could be executed if stored on | the NFS server that could be executed if stored on | |||
a non-NFS file system, unless the client's execution | a non-NFS file system, unless the client's execution | |||
subsystem also checks for execute permission bits. | subsystem also checks for execute permission bits. | |||
</t> | </li> | |||
<t> | <li> | |||
Even if the execution subsystem is checking for | Even if the execution subsystem is checking for | |||
execute permission bits, there are more potential | execute permission bits, there are more potential | |||
issues. For example, suppose the client is invoking access() | issues. For example, suppose the client is invoking access() | |||
to build a "path search table" of all executable | to build a "path search table" of all executable | |||
files in the user's "search path", where the path | files in the user's "search path", where the path | |||
is a list of directories each containing executable | is a list of directories each containing executable | |||
files. Suppose there are two files each in separate | files. Suppose there are two files each in separate | |||
directories of the search path, such that files have | directories of the search path, such that files have | |||
the same component name. In the first directory | the same component name. In the first directory | |||
the file has no execute permission bits set, | the file has no execute permission bits set, | |||
and in the second directory the file has execute | and in the second directory the file has execute | |||
bits set. The path search table will indicate that | bits set. The path search table will indicate that | |||
the first directory has the executable file, but | the first directory has the executable file, but | |||
the execute subsystem will fail to execute it. The | the execute subsystem will fail to execute it. The | |||
command shell might fail to try the second file in | command shell might fail to try the second file in | |||
the second directory. And even if it did, this is | the second directory. And even if it did, this is | |||
a potential performance issue. Clearly, the desired | a potential performance issue. Clearly, the desired | |||
outcome for the client is for the path search table | outcome for the client is for the path search table | |||
to not contain the first file. | to not contain the first file. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
To deal with the problems described above, the "smart client, | To deal with the problems described above, the "smart client, | |||
stupid server" principle is used. The client owns overall | stupid server" principle is used. The client owns overall | |||
responsibility for determining execute access and | responsibility for determining execute access and | |||
relies on the server to parse the execution permissions | relies on the server to parse the execution permissions | |||
within the file's mode, acl, and dacl attributes. The | within the file's mode, acl, and dacl attributes. The | |||
rules for the client and server follow: | rules for the client and server follow: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If the client is sending ACCESS in order to determine | If the client is sending ACCESS in order to determine | |||
if the user can read the file, the client SHOULD | if the user can read the file, the client <bcp14>SHOULD</bcp14> | |||
set ACCESS4_READ in the request's access field. | set ACCESS4_READ in the request's access field. | |||
</t> | </li> | |||
<t> | <li> | |||
If the client's operating environment only grants | If the client's operating environment only grants | |||
execution to the user if the user has execute access | execution to the user if the user has execute access | |||
according to the execute permissions in the mode, | according to the execute permissions in the mode, | |||
acl, and dacl attributes, then if the client wants | acl, and dacl attributes, then if the client wants | |||
to determine execute access, the client SHOULD send | to determine execute access, the client <bcp14>SHOULD</bcp14> send | |||
an ACCESS request with ACCESS4_EXECUTE bit set in the | an ACCESS request with ACCESS4_EXECUTE bit set in the | |||
request's access field. | request's access field. | |||
</t> | </li> | |||
<t> | <li> | |||
If the client's operating environment grants execution | If the client's operating environment grants execution | |||
to the user even if the user does not have execute | to the user even if the user does not have execute | |||
access according to the execute permissions in the | access according to the execute permissions in the | |||
mode, acl, and dacl attributes, then if the client | mode, acl, and dacl attributes, then if the client | |||
wants to determine execute access, it SHOULD send | wants to determine execute access, it <bcp14>SHOULD</bcp14> send | |||
an ACCESS request with both the ACCESS4_EXECUTE and | an ACCESS request with both the ACCESS4_EXECUTE and | |||
ACCESS4_READ bits set in the request's access field. This | ACCESS4_READ bits set in the request's access field. This | |||
way, if any read or execute permission grants the user | way, if any read or execute permission grants the user | |||
read or execute access (or if the server interprets | read or execute access (or if the server interprets | |||
the user as privileged), as indicated by the presence | the user as privileged), as indicated by the presence | |||
of ACCESS4_EXECUTE and/or ACCESS4_READ in the reply's | of ACCESS4_EXECUTE and/or ACCESS4_READ in the reply's | |||
access field, the client will be able to grant the | access field, the client will be able to grant the | |||
user execute access to the file. | user execute access to the file. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
If the server supports execute permission bits, or some other | If the server supports execute permission bits, or some other | |||
method for denoting executability (e.g., the suffix of the name | method for denoting executability (e.g., the suffix of the name | |||
of the file might indicate execute), it MUST check | of the file might indicate execute), it <bcp14>MUST</bcp14> check | |||
only execute permissions, not read permissions, when determining | only execute permissions, not read permissions, when determining | |||
whether or not the reply will have ACCESS4_EXECUTE set in the access | whether or not the reply will have ACCESS4_EXECUTE set in the access | |||
field. | field. | |||
The server MUST NOT also examine read permission bits when | The server <bcp14>MUST NOT</bcp14> also examine read permission bits when | |||
determining whether or not the reply will have ACCESS4_EXECUTE | determining whether or not the reply will have ACCESS4_EXECUTE | |||
set in the access field. Even if the server's | set in the access field. Even if the server's | |||
operating environment would grant execute access to the | operating environment would grant execute access to the | |||
user (e.g., the user is privileged), the server MUST | user (e.g., the user is privileged), the server <bcp14>MUST | |||
NOT reply with ACCESS4_EXECUTE set in reply's access | NOT</bcp14> reply with ACCESS4_EXECUTE set in reply's access | |||
field unless there is at least one execute permission | field unless there is at least one execute permission | |||
bit set in the mode, acl, or dacl attributes. In the | bit set in the mode, acl, or dacl attributes. In the | |||
case of acl and dacl, the "one execute permission bit" | case of acl and dacl, the "one execute permission bit" | |||
MUST be an ACE4_EXECUTE bit set in an ALLOW ACE. | <bcp14>MUST</bcp14> be an ACE4_EXECUTE bit set in an ALLOW ACE. | |||
</t> | </li> | |||
<t> | <li> | |||
If the server does not support execute permission | If the server does not support execute permission | |||
bits or some other method for denoting executability, it MUST NOT set ACCESS 4_EXECUTE in the | bits or some other method for denoting executability, it <bcp14>MUST NOT</bc p14> set ACCESS4_EXECUTE in the | |||
reply's supported and access fields. If the client | reply's supported and access fields. If the client | |||
set ACCESS4_EXECUTE in the ACCESS request's access | set ACCESS4_EXECUTE in the ACCESS request's access | |||
field, and ACCESS4_EXECUTE is not set in the reply's | field, and ACCESS4_EXECUTE is not set in the reply's | |||
supported field, then the client will have to send | supported field, then the client will have to send | |||
an ACCESS request with the ACCESS4_READ bit set in | an ACCESS request with the ACCESS4_READ bit set in | |||
the request's access field. | the request's access field. | |||
</t> | </li> | |||
<li> | ||||
<t> | If the server supports read permission bits, it <bcp14>MUST</bcp14> | |||
If the server supports read permission bits, it MUST | ||||
only check for read permissions in the mode, acl, | only check for read permissions in the mode, acl, | |||
and dacl attributes when it receives an ACCESS request | and dacl attributes when it receives an ACCESS request | |||
with ACCESS4_READ set in the access field. The server | with ACCESS4_READ set in the access field. The server | |||
MUST NOT also examine execute permission bits when | <bcp14>MUST NOT</bcp14> also examine execute permission bits when | |||
determining whether the reply will have ACCESS4_READ | determining whether the reply will have ACCESS4_READ | |||
set in the access field or not. | set in the access field or not. | |||
</t> | </li> | |||
</ul> | ||||
</list> | <t> | |||
Note that if the ACCESS reply has ACCESS4_READ | Note that if the ACCESS reply has ACCESS4_READ | |||
or ACCESS_EXECUTE set, then the user also has | or ACCESS_EXECUTE set, then the user also has | |||
permissions to OPEN (<xref target="OP_OPEN"/>) or | permissions to OPEN (<xref target="OP_OPEN" format="default"/>) or | |||
READ (<xref target="OP_READ"/>) the file. In other words, if | READ (<xref target="OP_READ" format="default"/>) the file. In other words, if | |||
the client sends an ACCESS request with the ACCESS4_READ | the client sends an ACCESS request with the ACCESS4_READ | |||
and ACCESS_EXECUTE set in the access field (or two | and ACCESS_EXECUTE set in the access field (or two | |||
separate requests, one with ACCESS4_READ set and the | separate requests, one with ACCESS4_READ set and the | |||
other with ACCESS4_EXECUTE set), and the reply has | other with ACCESS4_EXECUTE set), and the reply has | |||
just ACCESS4_EXECUTE set in the access field (or just | just ACCESS4_EXECUTE set in the access field (or just | |||
one reply has ACCESS4_EXECUTE set), then the user has | one reply has ACCESS4_EXECUTE set), then the user has | |||
authorization to OPEN or READ the file. | authorization to OPEN or READ the file. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_ACCESS_IMPLEMENTATION" title="IMPLEMENTATION | <section toc="exclude" anchor="OP_ACCESS_IMPLEMENTATION" numbered="true" | |||
"> | > | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
In general, it is not sufficient for the client to attempt to deduce | In general, it is not sufficient for the client to attempt to deduce | |||
access permissions by inspecting the uid, gid, and mode fields in the | access permissions by inspecting the uid, gid, and mode fields in the | |||
file attributes or by attempting to interpret the contents of the ACL | file attributes or by attempting to interpret the contents of the ACL | |||
attribute. This is because the server may perform uid or gid mapping | attribute. This is because the server may perform uid or gid mapping | |||
or enforce additional access-control restrictions. It is also | or enforce additional access-control restrictions. It is also | |||
possible that the server may not be in the same ID space as the | possible that the server may not be in the same ID space as the | |||
client. In these cases (and perhaps others), the client cannot | client. In these cases (and perhaps others), the client cannot | |||
reliably perform an access check with only current file attributes. | reliably perform an access check with only current file attributes. | |||
</t> | </t> | |||
<t> | <t> | |||
In the NFSv2 protocol, the only reliable way to determine | In the NFSv2 protocol, the only reliable way to determine | |||
whether an operation was allowed was to try it and see if it succeeded | whether an operation was allowed was to try it and see if it succeeded | |||
or failed. Using the ACCESS operation in the NFSv4.1 protocol, | or failed. Using the ACCESS operation in the NFSv4.1 protocol, | |||
the client can ask the server to indicate whether or not one or more | the client can ask the server to indicate whether or not one or more | |||
classes of operations are permitted. The ACCESS operation is provided | classes of operations are permitted. The ACCESS operation is provided | |||
to allow clients to check before doing a series of operations that | to allow clients to check before doing a series of operations that | |||
will result in an access failure. The OPEN operation provides a point | will result in an access failure. The OPEN operation provides a point | |||
where the server can verify access to the file object and a method to | where the server can verify access to the file object and a method to | |||
return that information to the client. The ACCESS operation is still | return that information to the client. The ACCESS operation is still | |||
useful for directory operations or for use in the case that the UNIX interface | useful for directory operations or for use in the case that the UNIX interface | |||
access() is used on the client. | access() is used on the client. | |||
</t> | </t> | |||
<t> | <t> | |||
The information returned by the server in response to an ACCESS call | The information returned by the server in response to an ACCESS call | |||
is not permanent. It was correct at the exact time that the server | is not permanent. It was correct at the exact time that the server | |||
performed the checks, but not necessarily afterwards. The server can | performed the checks, but not necessarily afterwards. The server can | |||
revoke access permission at any time. | revoke access permission at any time. | |||
</t> | </t> | |||
<t> | <t> | |||
The client should use the effective credentials of the user to build | The client should use the effective credentials of the user to build | |||
the authentication information in the ACCESS request used to determine | the authentication information in the ACCESS request used to determine | |||
access rights. It is the effective user and group credentials that | access rights. It is the effective user and group credentials that | |||
are used in subsequent READ and WRITE operations. | are used in subsequent READ and WRITE operations. | |||
</t> | </t> | |||
<t> | <t> | |||
Many implementations do not directly support the ACCESS4_DELETE | Many implementations do not directly support the ACCESS4_DELETE | |||
permission. Operating systems like UNIX will ignore the ACCESS4_DELETE | permission. Operating systems like UNIX will ignore the ACCESS4_DELETE | |||
bit if set on an access request on a non-directory object. In these | bit if set on an access request on a non-directory object. In these | |||
systems, delete permission on a file is determined by the access | systems, delete permission on a file is determined by the access | |||
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> | <section anchor="OP_CLOSE" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 4: CLOSE - Close File</name> | |||
$ --> | <section toc="exclude" anchor="OP_CLOSE_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <name>ARGUMENTS</name> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <sourcecode type="xdr"><![CDATA[ | |||
<section anchor="OP_CLOSE" title="Operation 4: CLOSE - Close File" > | ||||
<section toc="exclude" anchor="OP_CLOSE_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct CLOSE4args { | struct CLOSE4args { | |||
/* CURRENT_FH: object */ | /* CURRENT_FH: object */ | |||
seqid4 seqid; | seqid4 seqid; | |||
stateid4 open_stateid; | stateid4 open_stateid; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_CLOSE_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_CLOSE_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_CLOSE_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_CLOSE_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The CLOSE operation releases share reservations for the regular or | The CLOSE operation releases share reservations for the regular or | |||
named attribute file as specified by the current filehandle. The | named attribute file as specified by the current filehandle. The | |||
share reservations and other state information released at the server | share reservations and other state information released at the server | |||
as a result of this CLOSE are only those associated with the supplied | as a result of this CLOSE are only those associated with the supplied | |||
stateid. State associated with other OPENs is not affected. | stateid. State associated with other OPENs is not affected. | |||
</t> | </t> | |||
<t> | <t> | |||
If byte-range locks are held, the client SHOULD release all locks before | If byte-range locks are held, the client <bcp14>SHOULD</bcp14> release all | |||
sending a CLOSE. The server MAY free all outstanding locks on CLOSE, | locks before | |||
sending a CLOSE. The server <bcp14>MAY</bcp14> free all outstanding locks | ||||
on CLOSE, | ||||
but some servers may not support the CLOSE of a file that still has | but some servers may not support the CLOSE of a file that still has | |||
byte-range locks held. The server MUST return failure if any locks would | byte-range locks held. The server <bcp14>MUST</bcp14> return failure if a ny locks would | |||
exist after the CLOSE. | exist after the CLOSE. | |||
</t> | </t> | |||
<t> | <t> | |||
The argument seqid MAY have any value, and the server MUST ignore seqid. | The argument seqid <bcp14>MAY</bcp14> have any value, and the server <bcp1 | |||
</t> | 4>MUST</bcp14> ignore seqid. | |||
<t> | </t> | |||
<t> | ||||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
<t> | <t> | |||
The server MAY require that the combination of principal, security | The server <bcp14>MAY</bcp14> require that the combination of principal, se | |||
curity | ||||
flavor, and, if applicable, GSS mechanism | flavor, and, if applicable, GSS mechanism | |||
that sent the OPEN request also be the one to CLOSE | that sent the OPEN request also be the one to CLOSE | |||
the file. This might not be possible if credentials | the file. This might not be possible if credentials | |||
for the principal are no longer available. The server | for the principal are no longer available. The server | |||
MAY allow the machine credential or SSV credential | <bcp14>MAY</bcp14> allow the machine credential or SSV credential | |||
(see <xref target="OP_EXCHANGE_ID" />) to send CLOSE. | (see <xref target="OP_EXCHANGE_ID" format="default"/>) to send CLOSE. | |||
</t> | ||||
</section> | </t> | |||
<section toc="exclude" anchor="OP_CLOSE_IMPLEMENTATION" title="IMPLEMENTATION" | </section> | |||
> | <section toc="exclude" anchor="OP_CLOSE_IMPLEMENTATION" numbered="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
Even though CLOSE returns a stateid, this stateid is not useful to the | Even though CLOSE returns a stateid, this stateid is not useful to the | |||
client and should be treated as deprecated. CLOSE "shuts down" the | client and should be treated as deprecated. CLOSE "shuts down" the | |||
state associated with all OPENs for the file by a single open-owner. | state associated with all OPENs for the file by a single open-owner. | |||
As noted above, CLOSE will either release all file-locking state or | As noted above, CLOSE will either release all file-locking state or | |||
return an error. Therefore, the stateid returned by CLOSE is not | return an error. Therefore, the stateid returned by CLOSE is not | |||
useful for operations that follow. To help find any uses of | useful for operations that follow. To help find any uses of | |||
this stateid by clients, the server SHOULD return the invalid | this stateid by clients, the server <bcp14>SHOULD</bcp14> return the inval id | |||
special stateid (the "other" value is zero and the "seqid" field | special stateid (the "other" value is zero and the "seqid" field | |||
is NFS4_UINT32_MAX, see <xref target="special_stateid"/>). | is NFS4_UINT32_MAX, see <xref target="special_stateid" format="default"/>) | |||
</t> | . | |||
<t> | </t> | |||
<t> | ||||
A CLOSE operation may make delegations grantable | A CLOSE operation may make 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> | |||
<section anchor="OP_COMMIT" numbered="true" toc="default"> | ||||
<section anchor="OP_COMMIT" title="Operation 5: COMMIT - Commit Cached Data" > | <name>Operation 5: COMMIT - Commit Cached Data</name> | |||
<section toc="exclude" anchor="OP_COMMIT_ARGUMENTS" numbered="true"> | ||||
<section toc="exclude" anchor="OP_COMMIT_ARGUMENTS" title="ARGUMENTS"> | <name>ARGUMENTS</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct COMMIT4args { | struct COMMIT4args { | |||
/* CURRENT_FH: file */ | /* CURRENT_FH: file */ | |||
offset4 offset; | offset4 offset; | |||
count4 count; | count4 count; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_COMMIT_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_COMMIT_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_COMMIT_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_COMMIT_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The COMMIT operation forces or flushes uncommitted, modified data to stabl e storage for the | The COMMIT operation forces or flushes uncommitted, modified data to stabl e storage for the | |||
file specified by the current filehandle. The flushed data is that | file specified by the current filehandle. The flushed data is that | |||
which was previously written with one or more WRITE operations that had th e | which was previously written with one or more WRITE operations that had th e | |||
"committed" field of their results field set to UNSTABLE4. | "committed" field of their results field set to UNSTABLE4. | |||
</t> | </t> | |||
<t> | <t> | |||
The offset specifies the position within the file where the flush is | The offset specifies the position within the file where the flush is | |||
to begin. An offset value of zero means to flush data starting at | to begin. An offset value of zero means to flush data starting at | |||
the beginning of the file. The count specifies the number of bytes of | the beginning of the file. The count specifies the number of bytes of | |||
data to flush. If the count is zero, a flush from the offset to the end | data to flush. If the count is zero, a flush from the offset to the end | |||
of the file is done. | of the file is done. | |||
</t> | </t> | |||
<t> | <t> | |||
The server returns a write verifier upon successful completion of the | The server returns a write verifier upon successful completion of the | |||
COMMIT. The write verifier is used by the client to determine if the | COMMIT. The write verifier is used by the client to determine if the | |||
server has restarted between the initial WRITE operations and the | server has restarted between the initial WRITE operations and the | |||
COMMIT. The client does this by comparing the write verifier returned | COMMIT. The client does this by comparing the write verifier returned | |||
from the initial WRITE operations and the verifier returned by the COMMIT | from the initial WRITE operations and the verifier returned by the COMMIT | |||
operation. The server must vary the value of the write verifier at | operation. The server must vary the value of the write verifier at | |||
each server event or instantiation that may lead to a loss of | each server event or instantiation that may lead to a loss of | |||
uncommitted data. Most commonly this occurs when the server is | uncommitted data. Most commonly this occurs when the server is | |||
restarted; however, other events at the server may result in | restarted; however, other events at the server may result in | |||
uncommitted data loss as well. | uncommitted data loss as well. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_COMMIT_IMPLEMENTATION" title="IMPLEMENTATION | <section toc="exclude" anchor="OP_COMMIT_IMPLEMENTATION" numbered="true" | |||
"> | > | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
The COMMIT operation is similar in operation and semantics to the | The COMMIT operation is similar in operation and semantics to the | |||
<xref target="fsync">POSIX fsync()</xref> system interface that synchroniz es a file's state with the | <xref target="fsync" format="default">POSIX fsync()</xref> system interfac e that synchronizes a file's state with the | |||
disk (file data and metadata is flushed to disk or stable | disk (file data and metadata is flushed to disk or stable | |||
storage). COMMIT performs the same operation for a client, flushing | storage). COMMIT performs the same operation for a client, flushing | |||
any unsynchronized data and metadata on the server to the server's | any unsynchronized data and metadata on the server to the server's | |||
disk or stable storage for the specified file. Like fsync(), it may | disk or stable storage for the specified file. Like fsync(), it may | |||
be that there is some modified data or no modified data to | be that there is some modified data or no modified data to | |||
synchronize. The data may have been synchronized by the server's | synchronize. The data may have been synchronized by the server's | |||
normal periodic buffer synchronization activity. COMMIT should return | normal periodic buffer synchronization activity. COMMIT should return | |||
NFS4_OK, unless there has been an unexpected error. | NFS4_OK, unless there has been an unexpected error. | |||
</t> | </t> | |||
<t> | <t> | |||
COMMIT differs from fsync() in that it is possible for the client to | COMMIT differs from fsync() in that it is possible for the client to | |||
flush a range of the file (most likely triggered by a | flush a range of the file (most likely triggered by a | |||
buffer-reclamation scheme on the client before the file has been | buffer-reclamation scheme on the client before the file has been | |||
completely written). | completely written). | |||
</t> | </t> | |||
<t> | <t> | |||
The server implementation of COMMIT is reasonably simple. If the | The server implementation of COMMIT is reasonably simple. If the | |||
server receives a full file COMMIT request, that is, starting at offset | server receives a full file COMMIT request, that is, starting at offset | |||
zero and count zero, it should do the equivalent of applying fsync() to | zero and count zero, it should do the equivalent of applying fsync() to | |||
the entire file. | the entire file. | |||
Otherwise, it should arrange to have the modified data in the range | Otherwise, it should arrange to have the modified data in the range | |||
specified by offset and count to be flushed to stable storage. In | specified by offset and count to be flushed to stable storage. In | |||
both cases, any metadata associated with the file must be flushed to | both cases, any metadata associated with the file must be flushed to | |||
stable storage before returning. It is not an error for there to be | stable storage before returning. It is not an error for there to be | |||
nothing to flush on the server. This means that the data and metadata | nothing to flush on the server. This means that the data and metadata | |||
that needed to be flushed have already been flushed or lost during the | that needed to be flushed have already been flushed or lost during the | |||
last server failure. | last server failure. | |||
</t> | </t> | |||
<t> | <t> | |||
The client implementation of COMMIT is a little more complex. There | The client implementation of COMMIT is a little more complex. There | |||
are two reasons for wanting to commit a client buffer to stable | are two reasons for wanting to commit a client buffer to stable | |||
storage. The first is that the client wants to reuse a buffer. In | storage. The first is that the client wants to reuse a buffer. In | |||
this case, the offset and count of the buffer are sent to the server | this case, the offset and count of the buffer are sent to the server | |||
in the COMMIT request. The server then flushes any modified data based | in the COMMIT request. The server then flushes any modified data based | |||
on the offset and count, and flushes any modified metadata associated with the | on the offset and count, and flushes any modified metadata associated with the | |||
file. It then returns the status of the flush and the write verifier. | file. It then returns the status of the flush and the write verifier. | |||
The second reason for the client to generate a COMMIT is for a full | The second reason for the client to generate a COMMIT is for a full | |||
file flush, such as may be done at close. In this case, the client | file flush, such as may be done at close. In this case, the client | |||
would gather all of the buffers for this file that contain uncommitted | would gather all of the buffers for this file that contain uncommitted | |||
data, do the COMMIT operation with an offset of zero and count of zero, an d | data, do the COMMIT operation with an offset of zero and count of zero, an d | |||
then free all of those buffers. Any other dirty buffers would be sent | then free all of those buffers. Any other dirty buffers would be sent | |||
to the server in the normal fashion. | to the server in the normal fashion. | |||
</t> | </t> | |||
<t> | <t> | |||
After a buffer is written (via the WRITE operation) | After a buffer is written (via the WRITE operation) | |||
by the client with the "committed" field in the result of WRITE | by the client with the "committed" field in the result of WRITE | |||
set to UNSTABLE4, the buffer must be considered as modified by | set to UNSTABLE4, the buffer must be considered as modified by | |||
the client | the client | |||
until the buffer has either been flushed via a COMMIT operation or | until the buffer has either been flushed via a COMMIT operation or | |||
written via a WRITE operation with the "committed" field in the | written via a WRITE operation with the "committed" field in the | |||
result set to FILE_SYNC4 | result set to FILE_SYNC4 | |||
or DATA_SYNC4. This is done to prevent the buffer from being freed and | or DATA_SYNC4. This is done to prevent the buffer from being freed and | |||
reused before the data can be flushed to stable storage on the server. | reused before the data can be flushed to stable storage on the server. | |||
</t> | </t> | |||
<t> | <t> | |||
When a response is returned from either a WRITE or a COMMIT operation | When a response is returned from either a WRITE or a COMMIT operation | |||
and it contains a write verifier that differs from that previously | and it contains a write verifier that differs from that previously | |||
returned by the server, the client will need to retransmit all of the | returned by the server, the client will need to retransmit all of the | |||
buffers containing uncommitted data to the server. How this is | buffers containing uncommitted data to the server. How this is | |||
to be done is up to the implementor. If there is only one buffer of | to be done is up to the implementor. If there is only one buffer of | |||
interest, then it should be sent in a WRITE request | interest, then it should be sent in a WRITE request | |||
with the FILE_SYNC4 stable parameter. If there is more than one | with the FILE_SYNC4 stable parameter. If there is more than one | |||
buffer, it might be worthwhile retransmitting all of the buffers in | buffer, it might be worthwhile retransmitting all of the buffers in | |||
WRITE operations with the stable parameter set to UNSTABLE4 and then | WRITE operations with the stable parameter set to UNSTABLE4 and then | |||
retransmitting the COMMIT operation to flush all of the data on the | retransmitting the COMMIT operation to flush all of the data on the | |||
server to stable storage. However, if the server repeatably | server to stable storage. However, if the server repeatably | |||
returns from COMMIT a verifier that differs from that returned | returns from COMMIT a verifier that differs from that returned | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_CREATE" numbered="true" toc="default"> | |||
$ --> | <name>Operation 6: CREATE - Create a Non-Regular File Object</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_CREATE_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_CREATE" title="Operation 6: CREATE - Create a Non-Regular Fi | <sourcecode type="xdr"><![CDATA[ | |||
le Object" > | ||||
<section toc="exclude" anchor="OP_CREATE_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
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; | |||
default: | default: | |||
void; /* server should return NFS4ERR_BADTYPE */ | void; /* server should return NFS4ERR_BADTYPE */ | |||
}; | }; | |||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_CREATE_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_CREATE_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_CREATE_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_CREATE_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The CREATE operation creates a file object other than an | The CREATE operation creates a file object other than an | |||
ordinary file in a directory with a given name. | ordinary file in a directory with a given name. | |||
The OPEN operation MUST be used to create a | The OPEN operation <bcp14>MUST</bcp14> be used to create a | |||
regular file or a named attribute. | regular file or a named attribute. | |||
</t> | </t> | |||
<t> | <t> | |||
The current filehandle must be a directory: an object of type NF4DIR. If the current | The current filehandle must be a directory: an object of type NF4DIR. If the current | |||
filehandle is an attribute directory (type NF4ATTRDIR), the | filehandle is an attribute directory (type NF4ATTRDIR), the | |||
error NFS4ERR_WRONG_TYPE is returned. If the current file handle | error NFS4ERR_WRONG_TYPE is returned. If the current filehandle | |||
designates any other type of object, the error NFS4ERR_NOTDIR | designates any other type of object, the error NFS4ERR_NOTDIR | |||
results. | results. | |||
</t> | </t> | |||
<t> | <t> | |||
The objname specifies the name for the new object. | The objname specifies the name for the new object. | |||
The objtype determines the type of object to be | The objtype determines the type of object to be | |||
created: directory, symlink, etc. If the object | created: directory, symlink, etc. If the object | |||
type specified is that of an ordinary file, a | type specified is that of an ordinary file, a | |||
named attribute, or a named attribute directory, | named attribute, or a named attribute directory, | |||
the error NFS4ERR_BADTYPE results. | the error NFS4ERR_BADTYPE results. | |||
</t> | </t> | |||
<t> | <t> | |||
If an object of the same name already exists in the directory, the | If an object of the same name already exists in the directory, the | |||
server will return the error NFS4ERR_EXIST. | server will return the error NFS4ERR_EXIST. | |||
</t> | </t> | |||
<t> | <t> | |||
For the directory where the new file object was created, the server | For the directory where the new file object was created, the server | |||
returns change_info4 information in cinfo. With the atomic field of | returns change_info4 information in cinfo. With the atomic field of | |||
the change_info4 data type, the server will indicate if the before and | the change_info4 data type, the server will indicate if the before and | |||
after change attributes were obtained atomically with respect to the | after change attributes were obtained atomically with respect to the | |||
file object creation. | file object creation. | |||
</t> | </t> | |||
<t> | <t> | |||
If the objname has a length of zero, or if objname does not obey | If the objname has a length of zero, or if objname does not obey | |||
the UTF-8 definition, the error NFS4ERR_INVAL will be returned. | the UTF-8 definition, the error NFS4ERR_INVAL will be returned. | |||
</t> | </t> | |||
<t> | <t> | |||
The current filehandle is replaced by that of the new object. | The current filehandle is replaced by that of the new object. | |||
</t> | </t> | |||
<t> | <t> | |||
The createattrs specifies the initial set of attributes for the | The createattrs specifies the initial set of attributes for the | |||
object. The set of attributes may include any writable attribute | object. The set of attributes may include any writable attribute | |||
valid for the object type. When the operation is successful, the | valid for the object type. When the operation is successful, the | |||
server will return to the client an attribute mask signifying which | server will return to the client an attribute mask signifying which | |||
attributes were successfully set for the object. | attributes were successfully set for the object. | |||
</t> | </t> | |||
<t> | <t> | |||
If createattrs includes neither the owner attribute nor an ACL with an | If createattrs includes neither the owner attribute nor an ACL with an | |||
ACE for the owner, and if the server's file system both supports and | ACE for the owner, and if the server's file system both supports and | |||
requires an owner attribute (or an owner ACE), then the server MUST | requires an owner attribute (or an owner ACE), then the server <bcp14>MUST </bcp14> | |||
derive the owner (or the owner ACE). This would typically be from the | derive the owner (or the owner ACE). This would typically be from the | |||
principal indicated in the RPC credentials of the call, but the | principal indicated in the RPC credentials of the call, but the | |||
server's operating environment or file system semantics may dictate | server's operating environment or file system semantics may dictate | |||
other methods of derivation. Similarly, if createattrs includes | other methods of derivation. Similarly, if createattrs includes | |||
neither the group attribute nor a group ACE, and if the server's | neither the group attribute nor a group ACE, and if the server's | |||
file system both supports and requires the notion of a group attribute | file system both supports and requires the notion of a group attribute | |||
(or group ACE), the server MUST derive the group attribute (or the | (or group ACE), the server <bcp14>MUST</bcp14> derive the group attribute (or the | |||
corresponding owner ACE) for the file. This could be from the RPC | corresponding owner ACE) for the file. This could be from the RPC | |||
call's credentials, such as the group principal if the credentials | call's credentials, such as the group principal if the credentials | |||
include it (such as with AUTH_SYS), from the group identifier | include it (such as with AUTH_SYS), from the group identifier | |||
associated with the principal in the credentials (e.g., POSIX | associated with the principal in the credentials (e.g., POSIX | |||
systems have a <xref target="passwd">user database</xref> that has a group identifier for every | systems have a <xref target="passwd" format="default">user database</xref> that has a group identifier for every | |||
user identifier), inherited from the directory in which the object is crea ted, | user identifier), inherited from the directory in which the object is crea ted, | |||
or whatever else the server's operating environment or file system | or whatever else the server's operating environment or file system | |||
semantics dictate. This applies to the OPEN operation too. | semantics dictate. This applies to the OPEN operation too. | |||
</t> | </t> | |||
<t> | <t> | |||
Conversely, it is possible that the client will specify in createattrs an | Conversely, it is possible that the client will specify in createattrs an | |||
owner attribute, group attribute, or ACL that the principal indicated | owner attribute, group attribute, or ACL that the principal indicated | |||
the RPC call's credentials does not have permissions to create files | the RPC call's credentials does not have permissions to create files | |||
for. The error to be returned in this instance is NFS4ERR_PERM. This | for. The error to be returned in this instance is NFS4ERR_PERM. This | |||
applies to the OPEN operation too. | applies to the OPEN operation too. | |||
</t> | </t> | |||
<t> | <t> | |||
If the current filehandle designates a directory for which another | If the current filehandle designates a directory for which another | |||
client holds a directory delegation, then, unless the delegation | client holds a directory delegation, then, unless the delegation | |||
is such that the situation can be resolved by sending a notification, | is such that the situation can be resolved by sending a notification, | |||
the delegation MUST be recalled, and the CREATE operation MUST NOT proceed | the delegation <bcp14>MUST</bcp14> be recalled, and the CREATE operation < bcp14>MUST NOT</bcp14> proceed | |||
until the delegation is returned or revoked. Except where this | until the delegation is returned or revoked. 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 delegation remains outstanding. | returned to requests made while delegation remains outstanding. | |||
</t> | </t> | |||
<t> | <t> | |||
When the current filehandle designates a directory for which | When the current filehandle designates a directory for which | |||
one or more directory delegations exist, then, when those delegations | one or more directory delegations exist, then, when those delegations | |||
request such notifications, NOTIFY4_ADD_ENTRY will be generated | request such notifications, NOTIFY4_ADD_ENTRY will be generated | |||
as a result of this operation. | as a result of this operation. | |||
</t> | </t> | |||
<t> | <t> | |||
If the capability FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 is set | If the capability FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 is set | |||
(<xref target="utf8_caps"/>), | (<xref target="utf8_caps" format="default"/>), | |||
and a symbolic link is being created, then the content | and a symbolic link is being created, then the content | |||
of the symbolic link MUST be in UTF-8 encoding. | of the symbolic link <bcp14>MUST</bcp14> be in UTF-8 encoding. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_CREATE_IMPLEMENTATION" title="IMPLEMENTATION | <section toc="exclude" anchor="OP_CREATE_IMPLEMENTATION" numbered="true" | |||
"> | > | |||
<t> | <name>IMPLEMENTATION</name> | |||
<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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_DELEGPURGE" numbered="true" toc="default"> | |||
$ --> | <name>Operation 7: DELEGPURGE - Purge Delegations Awaiting Recovery</nam | |||
<!-- Copyright (C) The IETF Trust (2007) --> | e> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <section toc="exclude" anchor="OP_DELEGPURGE_ARGUMENTS" numbered="true"> | |||
<section anchor="OP_DELEGPURGE" title="Operation 7: DELEGPURGE - Purge Delegatio | <name>ARGUMENTS</name> | |||
ns Awaiting Recovery" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_DELEGPURGE_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct DELEGPURGE4args { | struct DELEGPURGE4args { | |||
clientid4 clientid; | clientid4 clientid; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_DELEGPURGE_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_DELEGPURGE_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct DELEGPURGE4res { | struct DELEGPURGE4res { | |||
nfsstat4 status; | nfsstat4 status; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_DELEGPURGE_DESCRIPTION" numbered="true | |||
</figure> | "> | |||
</section> | <name>DESCRIPTION</name> | |||
<t> | ||||
<section toc="exclude" anchor="OP_DELEGPURGE_DESCRIPTION" title="DESCRIPTION"> | ||||
<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 | |||
delayed by the server awaiting recovery of delegation information. | delayed by the server awaiting recovery of delegation information. | |||
</t> | </t> | |||
<t> | <t> | |||
The client is NOT specified by the clientid field of | The client is NOT specified by the clientid field of | |||
the request. The client SHOULD set the client field | the request. The client <bcp14>SHOULD</bcp14> set the client field | |||
to zero, and the server MUST ignore the clientid | to zero, and the server <bcp14>MUST</bcp14> ignore the clientid | |||
field. Instead, the server MUST derive the client ID | field. Instead, the server <bcp14>MUST</bcp14> derive the client ID | |||
from the value of the session ID in the arguments of | from the value of the session ID in the arguments of | |||
the SEQUENCE operation that precedes DELEGPURGE in | the SEQUENCE operation that precedes DELEGPURGE in | |||
the COMPOUND request. | the COMPOUND request. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
The DELEGPURGE operation should be used by clients that record delegation | The DELEGPURGE operation should be used by clients that record delegation | |||
information on stable storage on the client. In this case, | information on stable storage on the client. In this case, | |||
after the client recovers all delegations it knows of, | after the client recovers all delegations it knows of, | |||
it should immediately send a DELEGPURGE operation. | it should immediately send a DELEGPURGE operation. | |||
Doing so will notify the server that | Doing so will notify the server that | |||
no additional delegations for the client will be recovered allowing it | no additional delegations for the client will be recovered allowing it | |||
to free resources, and avoid delaying other clients which make requests | to free resources, and avoid delaying other clients which make requests | |||
that conflict with the unrecovered delegations. The set of | that conflict with the unrecovered delegations. The set of | |||
delegations known to the server and the client might be different. The | delegations known to the server and the client might be different. The | |||
reason for this is that after sending a request that | reason for this is that after sending a request that | |||
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 MAY support DELEGPURGE, but if it does not, it MUST NOT | The server <bcp14>MAY</bcp14> support DELEGPURGE, but if it does not, it < | |||
support CLAIM_DELEGATE_PREV and MUST NOT support CLAIM_DELEG_PREV_FH. | bcp14>MUST NOT</bcp14> | |||
</t> | support CLAIM_DELEGATE_PREV and <bcp14>MUST NOT</bcp14> support CLAIM_DELE | |||
</section> | G_PREV_FH. | |||
</section> | </t> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | </section> | |||
$ --> | </section> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <section anchor="OP_DELEGRETURN" numbered="true" toc="default"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>Operation 8: DELEGRETURN - Return Delegation</name> | |||
<section anchor="OP_DELEGRETURN" title="Operation 8: DELEGRETURN - Return Delega | <section toc="exclude" anchor="OP_DELEGRETURN_ARGUMENTS" numbered="true" | |||
tion" > | > | |||
<name>ARGUMENTS</name> | ||||
<section toc="exclude" anchor="OP_DELEGRETURN_ARGUMENTS" title="ARGUMENTS"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
struct DELEGRETURN4args { | struct DELEGRETURN4args { | |||
/* CURRENT_FH: delegated object */ | /* CURRENT_FH: delegated object */ | |||
stateid4 deleg_stateid; | stateid4 deleg_stateid; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_DELEGRETURN_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_DELEGRETURN_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct DELEGRETURN4res { | struct DELEGRETURN4res { | |||
nfsstat4 status; | nfsstat4 status; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_DELEGRETURN_DESCRIPTION" numbered="tru | |||
</figure> | e"> | |||
</section> | <name>DESCRIPTION</name> | |||
<t> | ||||
<section toc="exclude" anchor="OP_DELEGRETURN_DESCRIPTION" title="DESCRIPTION" | ||||
> | ||||
<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> | |||
<t> | <t> | |||
Delegations may be returned voluntarily (i.e., before | Delegations may be returned voluntarily (i.e., before | |||
the server has recalled them) or when recalled. In either case, the clien t must | the server has recalled them) or when recalled. In either case, the clien t must | |||
properly propagate state changed under the context of the delegation to | properly propagate state changed under the context of the delegation to | |||
the server before returning the delegation. | the server before returning the delegation. | |||
</t> | </t> | |||
<t> | <t> | |||
The server MAY require that the principal, security | The server <bcp14>MAY</bcp14> require that the principal, security | |||
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 MAY allow the machine credential | available. The server <bcp14>MAY</bcp14> allow the machine credential | |||
or SSV credential (see <xref target="OP_EXCHANGE_ID" | or SSV credential (see <xref target="OP_EXCHANGE_ID" format="default"/>) to | |||
/>) to send DELEGRETURN. | send DELEGRETURN. | |||
</t> | ||||
</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="OP_GETATTR" title="Operation 9: GETATTR - Get Attributes" > | ||||
<section toc="exclude" anchor="OP_GETATTR_ARGUMENTS" title="ARGUMENTS"> | </t> | |||
<figure> | </section> | |||
<artwork> | </section> | |||
<section anchor="OP_GETATTR" numbered="true" toc="default"> | ||||
<name>Operation 9: GETATTR - Get Attributes</name> | ||||
<section toc="exclude" anchor="OP_GETATTR_ARGUMENTS" numbered="true"> | ||||
<name>ARGUMENTS</name> | ||||
<sourcecode type="xdr"><![CDATA[ | ||||
struct GETATTR4args { | struct GETATTR4args { | |||
/* CURRENT_FH: object */ | /* CURRENT_FH: object */ | |||
bitmap4 attr_request; | bitmap4 attr_request; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_GETATTR_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_GETATTR_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_GETATTR_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_GETATTR_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The GETATTR operation will obtain attributes for the file system | The GETATTR operation will obtain attributes for the file system | |||
object specified by the current filehandle. The client sets a bit in | object specified by the current filehandle. The client sets a bit in | |||
the bitmap argument for each attribute value that it would like the | the bitmap argument for each attribute value that it would like the | |||
server to return. The server returns an attribute bitmap that | server to return. The server returns an attribute bitmap that | |||
indicates the attribute values that it was able to return, | indicates the attribute values that it was able to return, | |||
which will include all attributes requested by the client that | which will include all attributes requested by the client that | |||
are attributes supported by the server for the target | are attributes supported by the server for the target | |||
file system. This bitmap is followed by the attribute values ordered | file system. This bitmap is followed by the attribute values ordered | |||
lowest attribute number first. | lowest attribute number first. | |||
</t> | </t> | |||
<t> | <t> | |||
The server MUST return a value for each attribute that the client | The server <bcp14>MUST</bcp14> return a value for each attribute that the | |||
client | ||||
requests if the attribute is supported by the server for the target | requests if the attribute is supported by the server for the target | |||
file system. If the server does not support a particular attribute | file system. If the server does not support a particular attribute | |||
on the target file system, then it MUST NOT return the attribute value | on the target file system, then it <bcp14>MUST NOT</bcp14> return the attr | |||
and MUST NOT set the attribute bit in the result bitmap. The server | ibute value | |||
MUST return an error if it supports an attribute on the target | and <bcp14>MUST NOT</bcp14> set the attribute bit in the result bitmap. T | |||
he server | ||||
<bcp14>MUST</bcp14> return an error if it supports an attribute on the tar | ||||
get | ||||
but cannot obtain its value. In that case, no attribute values will | but cannot obtain its value. In that case, no attribute values will | |||
be returned. | be returned. | |||
</t> | </t> | |||
<t> | <t> | |||
File systems that are absent should be treated as having support for | File systems that are absent should be treated as having support for | |||
a very small set of attributes as described in | a very small set of attributes as described in | |||
<xref target="absent_getattr"/>, | <xref target="absent_getattr" format="default"/>, | |||
even if previously, when the file system was present, more attributes | even if previously, when the file system was present, more attributes | |||
were supported. | were supported. | |||
</t> | </t> | |||
<t> | <t> | |||
All servers MUST support the REQUIRED attributes as specified in | All servers <bcp14>MUST</bcp14> support the <bcp14>REQUIRED</bcp14> attrib | |||
<xref target="mandatory_attributes"/>, for all file systems, | utes as specified in | |||
<xref target="mandatory_attributes" format="default"/>, for all file syste | ||||
ms, | ||||
with the exception of absent file systems. | with the exception of absent file systems. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_GETATTR_IMPLEMENTATION" title="IMPLEMENTATIO | <section toc="exclude" anchor="OP_GETATTR_IMPLEMENTATION" numbered="true | |||
N"> | "> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
Suppose there is an OPEN_DELEGATE_WRITE delegation held by another client for | Suppose there is an OPEN_DELEGATE_WRITE delegation held by another client for | |||
the file | the file | |||
in question and size and/or change are among the set of attributes being i nterrogated. The server has two choices. | in question and size and/or change are among the set of attributes being i nterrogated. The server has two choices. | |||
First, the server can obtain the actual | First, the server can obtain the actual | |||
current value of these attributes from the client holding the delegation | current value of these attributes from the client holding the delegation | |||
by using the CB_GETATTR callback. Second, the server, particularly when t he | by using the CB_GETATTR callback. Second, the server, particularly when t he | |||
delegated client is unresponsive, can recall the | delegated client is unresponsive, can recall the | |||
delegation in question. The GETATTR MUST NOT proceed | delegation in question. The GETATTR <bcp14>MUST NOT</bcp14> proceed | |||
until one of the following occurs: | until one of the following occurs: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The requested attribute values are returned in the response to | The requested attribute values are returned in the response to | |||
CB_GETATTR. | CB_GETATTR. | |||
</t> | </li> | |||
<t> | <li> | |||
The OPEN_DELEGATE_WRITE delegation is returned. | The OPEN_DELEGATE_WRITE delegation is returned. | |||
</t> | </li> | |||
<t> | <li> | |||
The OPEN_DELEGATE_WRITE delegation is revoked. | The OPEN_DELEGATE_WRITE delegation is revoked. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_GETFH" numbered="true" toc="default"> | |||
$ --> | <name>Operation 10: GETFH - Get Current Filehandle</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_GETFH_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_GETFH" title="Operation 10: GETFH - Get Current Filehandle" | <sourcecode type="xdr"><![CDATA[ | |||
> | ||||
<section toc="exclude" anchor="OP_GETFH_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
/* CURRENT_FH: */ | /* CURRENT_FH: */ | |||
void; | void; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_GETFH_RESULTS" numbered="true"> | |||
<name>RESULTS</name> | ||||
<section toc="exclude" anchor="OP_GETFH_RESULTS" title="RESULTS"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_GETFH_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_GETFH_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
This operation returns the current filehandle value. | This operation returns the current filehandle value. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
<t> | <t> | |||
As described in <xref target="COMPOUND_Sizing_Issues"/>, GETFH | As described in <xref target="COMPOUND_Sizing_Issues" format="default"/>, | |||
is REQUIRED or RECOMMENDED to | GETFH | |||
is <bcp14>REQUIRED</bcp14> or <bcp14>RECOMMENDED</bcp14> to | ||||
immediately follow certain operations, and servers | immediately follow certain operations, and servers | |||
are free to reject such operations if | are free to reject such operations if | |||
the client fails to insert | the client fails to insert | |||
GETFH in the request as REQUIRED or RECOMMENDED. | GETFH in the request as <bcp14>REQUIRED</bcp14> or <bcp14>RECOMMENDED</bcp | |||
<xref target="open_getfh_issue"/> provides additional | 14>. | |||
justification for why GETFH MUST follow OPEN. | <xref target="open_getfh_issue" format="default"/> provides additional | |||
justification for why GETFH <bcp14>MUST</bcp14> follow OPEN. | ||||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_GETFH_IMPLEMENTATION" title="IMPLEMENTATION" | <section toc="exclude" anchor="OP_GETFH_IMPLEMENTATION" numbered="true"> | |||
> | <name>IMPLEMENTATION</name> | |||
<t> | <t> | |||
Operations that change the current filehandle like LOOKUP or CREATE do | Operations that change the current filehandle like LOOKUP or CREATE do | |||
not automatically return the new filehandle as a result. For | not automatically return the new filehandle as a result. For | |||
instance, if a client needs to look up a directory entry and obtain its | instance, if a client needs to look up a directory entry and obtain its | |||
filehandle, then the following request is needed. | filehandle, then the following request is needed. | |||
</t> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<list style="empty"> | <li> | |||
<t> | ||||
PUTFH (directory filehandle) | PUTFH (directory filehandle) | |||
</t> | </li> | |||
<t> | <li> | |||
LOOKUP (entry name) | LOOKUP (entry name) | |||
</t> | </li> | |||
<t> | <li> | |||
GETFH | GETFH | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="OP_LINK" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 11: LINK - Create Link to a File</name> | |||
$ --> | <section toc="exclude" anchor="OP_LINK_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <name>ARGUMENTS</name> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <sourcecode type="xdr"><![CDATA[ | |||
<section anchor="OP_LINK" title="Operation 11: LINK - Create Link to a File" > | ||||
<section toc="exclude" anchor="OP_LINK_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LINK_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_LINK_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LINK_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_LINK_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The LINK operation creates an additional newname for the file | The LINK operation creates an additional newname for the file | |||
represented by the saved filehandle, as set by the SAVEFH operation, | represented by the saved filehandle, as set by the SAVEFH operation, | |||
in the directory represented by the current filehandle. The existing | in the directory represented by the current filehandle. The existing | |||
file and the target directory must reside within the same file system | file and the target directory must reside within the same file system | |||
on the server. On success, the current filehandle will continue to be | on the server. On success, the current filehandle will continue to be | |||
the target directory. If an object exists in the target directory | the target directory. If an object exists in the target directory | |||
with the same name as newname, the server must return NFS4ERR_EXIST. | with the same name as newname, the server must return NFS4ERR_EXIST. | |||
</t> | </t> | |||
<t> | <t> | |||
For the target directory, the server returns change_info4 information | For the target directory, the server returns change_info4 information | |||
in cinfo. With the atomic field of the change_info4 data type, the | in cinfo. With the atomic field of the change_info4 data type, the | |||
server will indicate if the before and after change attributes were | server will indicate if the before and after change attributes were | |||
obtained atomically with respect to the link creation. | obtained atomically with respect to the link creation. | |||
</t> | </t> | |||
<t> | <t> | |||
If the newname has a length of zero, or if newname does not obey | If the newname has a length of zero, or if newname does not obey | |||
the UTF-8 definition, the error NFS4ERR_INVAL will be returned. | the UTF-8 definition, the error NFS4ERR_INVAL will be returned. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_LINK_IMPLEMENTATION" title="IMPLEMENTATION"> | <section toc="exclude" anchor="OP_LINK_IMPLEMENTATION" numbered="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
The server MAY impose restrictions on the LINK operation such that | <t> | |||
The server <bcp14>MAY</bcp14> impose restrictions on the LINK operation su | ||||
ch that | ||||
LINK may not be done when the file is open or when that open is done | LINK may not be done when the file is open or when that open is done | |||
by particular protocols, or with particular options or access modes. | by particular protocols, or with particular options or access modes. | |||
When LINK is rejected because of such restrictions, the error | When LINK is rejected because of such restrictions, the error | |||
NFS4ERR_FILE_OPEN is returned. | NFS4ERR_FILE_OPEN is returned. | |||
</t> | </t> | |||
<t> | <t> | |||
If a server does implement such restrictions and those restrictions | If a server does implement such restrictions and those restrictions | |||
include cases of NFSv4 opens preventing successful execution of | include cases of NFSv4 opens preventing successful execution of | |||
a link, the server needs to recall any delegations that could | a link, the server needs to recall any delegations that could | |||
hide the existence of opens relevant to that decision. The reason | hide the existence of opens relevant to that decision. The reason | |||
is that when a client holds a delegation, the server | is that when a client holds a delegation, the server | |||
might not have an accurate account of the opens for that client, since | might not have an accurate account of the opens for that client, since | |||
the client may execute OPENs and CLOSEs locally. The LINK operation | the client may execute OPENs and CLOSEs locally. The LINK operation | |||
must be delayed only until a definitive result can be obtained. | must be delayed only until a definitive result can be obtained. | |||
For example, suppose there are multiple delegations and one of them establ ishes | For example, suppose there are multiple delegations and one of them establ ishes | |||
an open whose presence would prevent the link. Given the server's | an open whose presence would prevent the link. Given the server's | |||
semantics, NFS4ERR_FILE_OPEN may be returned to the caller as soon | semantics, NFS4ERR_FILE_OPEN may be returned to the caller as soon | |||
as that delegation is returned without waiting for other delegations | as that delegation is returned without waiting for other delegations | |||
to be returned. Similarly, if such opens are not associated with | to be returned. Similarly, if such opens are not associated with | |||
delegations, NFS4ERR_FILE_OPEN can be returned immediately with no | delegations, NFS4ERR_FILE_OPEN can be returned immediately with no | |||
delegation recall being done. | delegation recall being done. | |||
</t> | </t> | |||
<t> | <t> | |||
If the current filehandle designates a directory for which another | If the current filehandle designates a directory for which another | |||
client holds a directory delegation, then, unless the delegation | client holds a directory delegation, then, unless the delegation | |||
is such that the situation can be resolved by sending a notification, | is such that the situation can be resolved by sending a notification, | |||
the delegation MUST be recalled, and the operation cannot be | the delegation <bcp14>MUST</bcp14> be recalled, and the operation cannot b e | |||
performed successfully until the delegation is returned or revoked. Excep t where this | performed successfully until the delegation is returned or revoked. Excep t 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 delegation remains outstanding. | returned to requests made while delegation remains outstanding. | |||
</t> | </t> | |||
<t> | <t> | |||
When the current filehandle designates a directory for which | When the current filehandle designates a directory for which | |||
one or more directory delegations exist, then, when those delegations | one or more directory delegations exist, then, when those delegations | |||
request such notifications, instead of a recall, | request such notifications, instead of a recall, | |||
NOTIFY4_ADD_ENTRY will be generated | NOTIFY4_ADD_ENTRY will be generated | |||
as a result of the LINK operation. | as a result of the LINK operation. | |||
</t> | </t> | |||
<t> | <t> | |||
If the current file system supports the numlinks attribute, and | If the current file system supports the numlinks attribute, and | |||
other clients have delegations to the file being linked, then those | other clients have delegations to the file being linked, then those | |||
delegations MUST be recalled and the LINK operation MUST NOT proceed until | delegations <bcp14>MUST</bcp14> be recalled and the LINK operation <bcp14> MUST NOT</bcp14> proceed until | |||
all delegations are returned or revoked. Except where this | all delegations are returned or revoked. 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 delegation remains outstanding. | returned to requests made while delegation remains outstanding. | |||
</t> | </t> | |||
<t> | <t> | |||
Changes to any property of the "hard" linked files are reflected in | Changes to any property of the "hard" linked files are reflected in | |||
all of the linked files. When a link is made to a file, the | all of the linked files. When a link is made to a file, the | |||
attributes for the file should have a value for numlinks that is one | attributes for the file should have a value for numlinks that is one | |||
greater than the value before the LINK operation. | greater than the value before the LINK operation. | |||
</t> | </t> | |||
<t> | <t> | |||
The statement "file and the target directory must reside within the | The statement "file and the target directory must reside within the | |||
same file system on the server" means that the fsid fields in the | same file system on the server" means that the fsid fields in the | |||
attributes for the objects are the same. If they reside on | attributes for the objects are the same. If they reside on | |||
different file systems, the error NFS4ERR_XDEV is returned. | different file systems, the error NFS4ERR_XDEV is returned. | |||
This error may be returned by some servers when there is an | This error may be returned by some servers when there is an | |||
internal partitioning of a file system that the LINK operation | internal partitioning of a file system that the LINK operation | |||
would violate. | would violate. | |||
</t> | </t> | |||
<t> | <t> | |||
On some | On some | |||
servers, "." and ".." are illegal values for newname | servers, "." and ".." are illegal values for newname | |||
and the error NFS4ERR_BADNAME will be returned if they are specified. | and the error NFS4ERR_BADNAME will be returned if they are specified. | |||
</t> | </t> | |||
<t> | <t> | |||
When the current filehandle designates a named attribute directory | When the current filehandle designates a named attribute directory | |||
and the object to be linked (the saved filehandle) is not a named | and the object to be linked (the saved filehandle) is not a named | |||
attribute for the same object, the error NFS4ERR_XDEV MUST be | attribute for the same object, the error NFS4ERR_XDEV <bcp14>MUST</bcp14> be | |||
returned. When the saved filehandle designates a named attribute | returned. When the saved filehandle designates a named attribute | |||
and the current filehandle is not the appropriate named attribute | and the current filehandle is not the appropriate named attribute | |||
directory, the error NFS4ERR_XDEV MUST also be returned. | directory, the error NFS4ERR_XDEV <bcp14>MUST</bcp14> also be returned. | |||
</t> | </t> | |||
<t> | <t> | |||
When the current filehandle designates a named attribute directory | When the current filehandle designates a named attribute directory | |||
and the object to be linked (the saved filehandle) is a named | and the object to be linked (the saved filehandle) is a named | |||
attribute within that directory, the server may return | attribute within that directory, the server may return | |||
the error NFS4ERR_NOTSUPP. | the error NFS4ERR_NOTSUPP. | |||
</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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_LOCK" numbered="true" toc="default"> | |||
$ --> | <name>Operation 12: LOCK - Create Lock</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_LOCK_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_LOCK" title="Operation 12: LOCK - Create Lock" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_LOCK_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
/* | /* | |||
* 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 30904 ¶ | skipping to change at line 31253 ¶ | |||
/* | /* | |||
* LOCK/LOCKT/LOCKU: Record lock management | * LOCK/LOCKT/LOCKU: Record lock management | |||
*/ | */ | |||
struct LOCK4args { | struct LOCK4args { | |||
/* 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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LOCK_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_LOCK_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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; | |||
}; | }; | |||
union LOCK4res switch (nfsstat4 status) { | union LOCK4res switch (nfsstat4 status) { | |||
case NFS4_OK: | case NFS4_OK: | |||
LOCK4resok resok4; | LOCK4resok resok4; | |||
case NFS4ERR_DENIED: | case NFS4ERR_DENIED: | |||
LOCK4denied denied; | LOCK4denied denied; | |||
default: | default: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LOCK_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_LOCK_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The LOCK operation requests a byte-range lock for the byte-range specified | The LOCK operation requests a byte-range lock for the byte-range specified | |||
by the offset and length parameters, and lock type specified in | by the offset and length parameters, and lock type specified in | |||
the locktype parameter. If this is a reclaim request, the | the locktype parameter. If this is a reclaim request, the | |||
reclaim parameter will be TRUE. | reclaim parameter will be TRUE. | |||
</t> | </t> | |||
<t> | <t> | |||
Bytes in a file may be locked even if those bytes are not currently | Bytes in a file may be locked even if those bytes are not currently | |||
allocated to the file. To lock the file from a specific offset | allocated to the file. To lock the file from a specific offset | |||
through the end-of-file (no matter how long the file actually is) use | through the end-of-file (no matter how long the file actually is) use | |||
a length field equal to NFS4_UINT64_MAX. | a length field equal to NFS4_UINT64_MAX. | |||
The server MUST return NFS4ERR_INVAL under the following | The server <bcp14>MUST</bcp14> return NFS4ERR_INVAL under the following | |||
combinations of length and offset: | combinations of length and offset: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Length is equal to zero. | Length is equal to zero. | |||
</t> | </li> | |||
<t> | <li> | |||
Length is not equal to NFS4_UINT64_MAX, and the sum of length | Length is not equal to NFS4_UINT64_MAX, and the sum of length | |||
and offset exceeds NFS4_UINT64_MAX. | and offset exceeds NFS4_UINT64_MAX. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
</t> | ||||
<t> | ||||
32-bit servers are servers that support locking for | 32-bit servers are servers that support locking for | |||
byte offsets that fit within 32 bits (i.e., less than | byte offsets that fit within 32 bits (i.e., less than | |||
or equal to NFS4_UINT32_MAX). If the client specifies a | or equal to NFS4_UINT32_MAX). If the client specifies a | |||
range that overlaps one or more bytes beyond offset | range that overlaps one or more bytes beyond offset | |||
NFS4_UINT32_MAX but does not end at offset | NFS4_UINT32_MAX but does not end at offset | |||
NFS4_UINT64_MAX, then such a 32-bit server MUST return the | NFS4_UINT64_MAX, then such a 32-bit server <bcp14>MUST</bcp14> return the | |||
error NFS4ERR_BAD_RANGE. | error NFS4ERR_BAD_RANGE. | |||
</t> | </t> | |||
<t> | <t> | |||
If the server returns NFS4ERR_DENIED, the | If the server returns NFS4ERR_DENIED, the | |||
owner, offset, and length | owner, offset, and length | |||
of a conflicting lock are returned. | of a conflicting lock are returned. | |||
</t> | </t> | |||
<t> | <t> | |||
The locker argument specifies the lock-owner that is associated with | The locker argument specifies the lock-owner that is associated with | |||
the LOCK operation. The locker4 structure is a switched union that | the LOCK operation. The locker4 structure is a switched union that | |||
indicates whether the client has already created byte-range locking | indicates whether the client has already created byte-range locking | |||
state associated with the current open file and lock-owner. In the | state associated with the current open file and lock-owner. In the | |||
case in which it has, the argument is just a stateid representing | case in which it has, the argument is just a stateid representing | |||
the set of | the set of | |||
locks associated with that open file and lock-owner, together with | locks associated with that open file and lock-owner, together with | |||
a lock_seqid value that MAY be any value and MUST be ignored | a lock_seqid value that <bcp14>MAY</bcp14> be any value and <bcp14>MUST</b cp14> be ignored | |||
by the server. | by the server. | |||
In the case where no byte-range locking state has been established, or the client | In the case where no byte-range locking state has been established, or the client | |||
does not have the stateid available, the argument contains the | does not have the stateid available, the argument contains the | |||
stateid of the open file with which this lock is to be associated, | stateid of the open file with which this lock is to be associated, | |||
together with the lock-owner with which the lock is to be associated. | together with the lock-owner with which the lock is to be associated. | |||
The open_to_lock_owner case covers the very first lock done by a | The open_to_lock_owner case covers the very first lock done by a | |||
lock-owner for a given open file and offers a method to use the | lock-owner for a given open file and offers a method to use the | |||
established state of the open_stateid to transition to the use of | established state of the open_stateid to transition to the use of | |||
a lock stateid. | a lock stateid. | |||
</t> | </t> | |||
<t> | <t> | |||
The following fields of the locker parameter MAY be | The following fields of the locker parameter <bcp14>MAY</bcp14> be | |||
set to any value by the client and MUST be ignored | set to any value by the client and <bcp14>MUST</bcp14> be ignored | |||
by the server: | by the server: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The clientid field of the lock_owner | The clientid field of the lock_owner | |||
field of the open_owner field | field of the open_owner field | |||
(locker.open_owner.lock_owner.clientid). The | (locker.open_owner.lock_owner.clientid). The | |||
reason the server MUST ignore the clientid field | reason the server <bcp14>MUST</bcp14> ignore the clientid field | |||
is that the server MUST derive the client ID from | is that the server <bcp14>MUST</bcp14> derive the client ID from | |||
the session ID from the SEQUENCE operation of the | the session ID from the SEQUENCE operation of the | |||
COMPOUND request. | COMPOUND request. | |||
</t> | </li> | |||
<t> | <li> | |||
The open_seqid and lock_seqid fields of the | The open_seqid and lock_seqid fields of the | |||
open_owner field (locker.open_owner.open_seqid and | open_owner field (locker.open_owner.open_seqid and | |||
locker.open_owner.lock_seqid). | locker.open_owner.lock_seqid). | |||
</t> | </li> | |||
<t> | <li> | |||
The lock_seqid field of the lock_owner field | The lock_seqid field of the lock_owner field | |||
(locker.lock_owner.lock_seqid). | (locker.lock_owner.lock_seqid). | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Note that the client ID appearing in a LOCK4denied | Note that the client ID appearing in a LOCK4denied | |||
structure is the actual client associated with the | structure is the actual client associated with the | |||
conflicting lock, whether this is the client ID | conflicting lock, whether this is the client ID | |||
associated with the current session or a different | associated with the current session or a different | |||
one. Thus, if the server returns NFS4ERR_DENIED, | one. Thus, if the server returns NFS4ERR_DENIED, | |||
it MUST set the clientid field of the owner field of the | it <bcp14>MUST</bcp14> set the clientid field of the owner field of the | |||
denied field. | denied field. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
If the current filehandle is not an ordinary file, an error will be | If the current filehandle is not an ordinary file, an error will be | |||
returned to the client. In the case that the current filehandle | returned to the client. In the case that the current filehandle | |||
represents an object of type NF4DIR, NFS4ERR_ISDIR is returned. | represents an object of type NF4DIR, NFS4ERR_ISDIR is returned. | |||
If the current filehandle designates a symbolic link, | If the current filehandle designates a symbolic link, | |||
NFS4ERR_SYMLINK is returned. In all other cases, | NFS4ERR_SYMLINK is returned. In all other cases, | |||
NFS4ERR_WRONG_TYPE is returned. | NFS4ERR_WRONG_TYPE is returned. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_LOCK_IMPLEMENTATION" title="IMPLEMENTATION"> | <section toc="exclude" anchor="OP_LOCK_IMPLEMENTATION" numbered="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
If the server is unable to determine the exact offset and length of | If the server is unable to determine the exact offset and length of | |||
the conflicting byte-range lock, the same offset and length that were prov ided in | the conflicting byte-range lock, the same offset and length that were prov ided in | |||
the arguments should be returned in the denied results. | the arguments should be returned in the denied results. | |||
</t> | </t> | |||
<t> | <t> | |||
LOCK operations are subject to permission checks and to checks against | LOCK operations are subject to permission checks and to checks against | |||
the access type of the associated file. However, the specific right | the access type of the associated file. However, the specific right | |||
and modes required for various types of locks reflect the semantics of | and modes required for various types of locks reflect the semantics of | |||
the server-exported file system, and are not specified by the protocol. | the server-exported file system, and are not specified by the protocol. | |||
For example, Windows 2000 allows a write lock of a file open for read acce ss, | For example, Windows 2000 allows a write lock of a file open for read acce ss, | |||
while a POSIX-compliant system does not. | while a POSIX-compliant system does not. | |||
</t> | </t> | |||
<t> | <t> | |||
When the client sends a LOCK operation that corresponds to a range that | When the client sends a LOCK operation that corresponds to a range that | |||
the lock-owner has locked already (with the same or different lock | the lock-owner has locked already (with the same or different lock | |||
type), or to a sub-range of such a range, or to a byte-range that | type), or to a sub-range of such a range, or to a byte-range that | |||
includes multiple locks already granted to that lock-owner, in whole or | includes multiple locks already granted to that lock-owner, in whole or | |||
in part, and the server does not support such locking operations | in part, and the server does not support such locking operations | |||
(i.e., does not support POSIX locking semantics), the server will | (i.e., does not support POSIX locking semantics), the server will | |||
return the error NFS4ERR_LOCK_RANGE. In that case, the client may | return the error NFS4ERR_LOCK_RANGE. In that case, the client may | |||
return an error, or it may emulate the required operations, using only | return an error, or it may emulate the required operations, using only | |||
LOCK for ranges that do not include any bytes already locked by that | LOCK for ranges that do not include any bytes already locked by that | |||
lock-owner and LOCKU of locks held by that lock-owner (specifying an | lock-owner and LOCKU of locks held by that lock-owner (specifying an | |||
exactly matching range and type). Similarly, when the client sends a | exactly matching range and type). Similarly, when the client sends a | |||
LOCK operation that amounts to upgrading (changing from a READ_LT lock to a | LOCK operation that amounts to upgrading (changing from a READ_LT lock to a | |||
WRITE_LT lock) or downgrading (changing from WRITE_LT lock to a READ_LT lo ck) | WRITE_LT lock) or downgrading (changing from WRITE_LT lock to a READ_LT lo ck) | |||
an existing byte-range lock, and the server does not support such a lock, | an existing byte-range lock, and the server does not support such a lock, | |||
the server will return NFS4ERR_LOCK_NOTSUPP. Such operations may not | the server will return NFS4ERR_LOCK_NOTSUPP. Such operations may not | |||
perfectly reflect the required semantics in the face of conflicting | perfectly reflect the required semantics in the face of conflicting | |||
LOCK operations from other clients. | LOCK operations from other clients. | |||
</t> | </t> | |||
<t> | <t> | |||
When a client holds an OPEN_DELEGATE_WRITE delegation, the client holding that | When a client holds an OPEN_DELEGATE_WRITE delegation, the client holding that | |||
delegation is assured that there are no opens by other clients. | delegation is assured that there are no opens by other clients. | |||
Thus, there can be no conflicting LOCK operations from such clients. | Thus, there can be no conflicting LOCK operations from such clients. | |||
Therefore, the client may be handling locking requests locally, | Therefore, the client may be handling locking requests locally, | |||
without | without | |||
doing LOCK operations on the server. If it does that, it must be | doing LOCK operations on the server. If it does that, it must be | |||
prepared to update the lock status on the server, by sending | prepared to update the lock status on the server, by sending | |||
appropriate LOCK and LOCKU operations before returning | appropriate LOCK and LOCKU operations before returning | |||
the delegation. | the delegation. | |||
</t> | </t> | |||
<t> | <t> | |||
When one or more clients hold OPEN_DELEGATE_READ delegations, any LOCK ope ration | When one or more clients hold OPEN_DELEGATE_READ delegations, any LOCK ope ration | |||
where the server is implementing mandatory locking semantics MUST | 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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_LOCKT" numbered="true" toc="default"> | |||
$ --> | <name>Operation 13: LOCKT - Test for Lock</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_LOCKT_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_LOCKT" title="Operation 13: LOCKT - Test for Lock" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_LOCKT_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LOCKT_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_LOCKT_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LOCKT_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_LOCKT_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The LOCKT operation tests the lock as specified in the arguments. If | The LOCKT operation tests the lock as specified in the arguments. If | |||
a conflicting lock exists, the owner, offset, length, and type of the | a conflicting lock exists, the owner, offset, length, and type of the | |||
conflicting lock are returned. | conflicting lock are returned. | |||
The owner field in the results includes the client ID of the owner of | The owner field in the results includes the client ID of the owner of | |||
the conflicting lock, whether this is the client ID associated with the | the conflicting lock, whether this is the client ID associated with the | |||
current session or a different client ID. | current session or a different client ID. | |||
If no lock is held, nothing other than | If no lock is held, nothing other than | |||
NFS4_OK is returned. Lock types READ_LT and READW_LT are processed in | NFS4_OK is returned. Lock types READ_LT and READW_LT are processed in | |||
the same way in that a conflicting lock test is done without regard to | the same way in that a conflicting lock test is done without regard to | |||
blocking or non-blocking. The same is true for WRITE_LT and WRITEW_LT. | blocking or non-blocking. The same is true for WRITE_LT and WRITEW_LT. | |||
</t> | </t> | |||
<t> | <t> | |||
The ranges are specified as for LOCK. The NFS4ERR_INVAL and | The ranges are specified as for LOCK. The NFS4ERR_INVAL and | |||
NFS4ERR_BAD_RANGE errors are returned under the same circumstances | NFS4ERR_BAD_RANGE errors are returned under the same circumstances | |||
as for LOCK. | as for LOCK. | |||
</t> | </t> | |||
<t> | <t> | |||
The clientid field of the owner MAY be set to | The clientid field of the owner <bcp14>MAY</bcp14> be set to | |||
any value by the client and MUST be ignored by | any value by the client and <bcp14>MUST</bcp14> be ignored by | |||
the server. The reason the server MUST ignore the | the server. The reason the server <bcp14>MUST</bcp14> ignore the | |||
clientid field is that the server MUST derive the | clientid field is that the server <bcp14>MUST</bcp14> derive the | |||
client ID from the session ID from the SEQUENCE | client ID from the session ID from the SEQUENCE | |||
operation of the COMPOUND request. | operation of the COMPOUND request. | |||
</t> | </t> | |||
<t> | <t> | |||
If the current filehandle is not an ordinary file, an error will be | If the current filehandle is not an ordinary file, an error will be | |||
returned to the client. In the case that the current filehandle | returned to the client. In the case that the current filehandle | |||
represents an object of type NF4DIR, NFS4ERR_ISDIR is returned. | represents an object of type NF4DIR, NFS4ERR_ISDIR is returned. | |||
If the current filehandle designates a symbolic link, | If the current filehandle designates a symbolic link, | |||
NFS4ERR_SYMLINK is returned. In all other cases, | NFS4ERR_SYMLINK is returned. In all other cases, | |||
NFS4ERR_WRONG_TYPE is returned. | NFS4ERR_WRONG_TYPE is returned. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_LOCKT_IMPLEMENTATION" title="IMPLEMENTATION" | <section toc="exclude" anchor="OP_LOCKT_IMPLEMENTATION" numbered="true"> | |||
> | <name>IMPLEMENTATION</name> | |||
<t> | <t> | |||
If the server is unable to determine the exact offset | If the server is unable to determine the exact offset | |||
and length of the conflicting lock, the same offset | and length of the conflicting lock, the same offset | |||
and length that were provided in the arguments should | and length that were provided in the arguments should | |||
be returned in the denied results. | be returned in the denied results. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
LOCKT uses a lock_owner4 rather a stateid4, as is used in | LOCKT uses a lock_owner4 rather a stateid4, as is used in | |||
LOCK to identify the owner. This is because the client does not | LOCK to identify the owner. This is because the client does not | |||
have to open the file to test for the existence of a lock, so | have to open the file to test for the existence of a lock, so | |||
a stateid might not be available. | a stateid might not be available. | |||
</t> | </t> | |||
<t> | <t> | |||
As noted in <xref target="OP_LOCK_IMPLEMENTATION"/>, some | As noted in <xref target="OP_LOCK_IMPLEMENTATION" format="default"/>, some | |||
servers may return NFS4ERR_LOCK_RANGE to certain (otherwise | servers may return NFS4ERR_LOCK_RANGE to certain (otherwise | |||
non-conflicting) LOCK operations that overlap ranges already | non-conflicting) LOCK operations that overlap ranges already | |||
granted to the current lock-owner. | granted to the current lock-owner. | |||
</t> | </t> | |||
<t> | ||||
<t> | The LOCKT operation's test for conflicting locks <bcp14>SHOULD</bcp14> exc | |||
The LOCKT operation's test for conflicting locks SHOULD exclude | lude | |||
locks for the current lock-owner, and thus should return NFS4_OK in | locks for the current lock-owner, and thus should return NFS4_OK in | |||
such cases. Note that this means that a server might return | such cases. Note that this means that a server might return | |||
NFS4_OK to a LOCKT request even though a LOCK operation for the | NFS4_OK to a LOCKT request even though a LOCK operation for the | |||
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" />) to handle LOCK | (see <xref target="OP_LOCK_IMPLEMENTATION" format="default"/>) to handle L OCK | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_LOCKU" numbered="true" toc="default"> | |||
$ --> | <name>Operation 14: LOCKU - Unlock File</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_LOCKU_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_LOCKU" title="Operation 14: LOCKU - Unlock File" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_LOCKU_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LOCKU_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_LOCKU_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LOCKU_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_LOCKU_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The LOCKU operation unlocks the byte-range lock specified by the | The LOCKU operation unlocks the byte-range lock specified by the | |||
parameters. The client may set the locktype field to any value that is | parameters. The client may set the locktype field to any value that is | |||
legal for the nfs_lock_type4 enumerated type, and the server MUST | legal for the nfs_lock_type4 enumerated type, and the server <bcp14>MUST</ bcp14> | |||
accept any legal value for locktype. Any legal value for locktype has | accept any legal value for locktype. Any legal value for locktype has | |||
no effect on the success or failure of the LOCKU operation. | no effect on the success or failure of the LOCKU operation. | |||
</t> | </t> | |||
<t> | <t> | |||
The ranges are specified as for LOCK. The NFS4ERR_INVAL and | The ranges are specified as for LOCK. The NFS4ERR_INVAL and | |||
NFS4ERR_BAD_RANGE errors are returned under the same circumstances as | NFS4ERR_BAD_RANGE errors are returned under the same circumstances as | |||
for LOCK. | for LOCK. | |||
</t> | </t> | |||
<t> | <t> | |||
The seqid parameter MAY be any value and the server MUST ignore it. | The seqid parameter <bcp14>MAY</bcp14> be any value and the server <bcp14> | |||
</t> | MUST</bcp14> ignore it. | |||
<t> | </t> | |||
<t> | ||||
If the current filehandle is not an ordinary file, an error will be | If the current filehandle is not an ordinary file, an error will be | |||
returned to the client. In the case that the current filehandle | returned to the client. In the case that the current filehandle | |||
represents an object of type NF4DIR, NFS4ERR_ISDIR is returned. | represents an object of type NF4DIR, NFS4ERR_ISDIR is returned. | |||
If the current filehandle designates a symbolic link, | If the current filehandle designates a symbolic link, | |||
NFS4ERR_SYMLINK is returned. In all other cases, | NFS4ERR_SYMLINK is returned. In all other cases, | |||
NFS4ERR_WRONG_TYPE is returned. | NFS4ERR_WRONG_TYPE is returned. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
<t> | <t> | |||
The server MAY require that the principal, security | The server <bcp14>MAY</bcp14> require that the principal, security | |||
flavor, and if applicable, the GSS mechanism, combination | flavor, and if applicable, the GSS mechanism, combination | |||
that sent a LOCK operation also be the one to send | that sent a LOCK operation also be the one to send | |||
LOCKU on the file. This might not be possible | LOCKU 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 MAY allow the machine credential | available. The server <bcp14>MAY</bcp14> allow the machine credential | |||
or SSV credential (see <xref target="OP_EXCHANGE_ID" | or SSV credential (see <xref target="OP_EXCHANGE_ID" format="default"/>) to | |||
/>) to send LOCKU. | send LOCKU. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_LOCKU_IMPLEMENTATION" title="IMPLEMENTATION" | <section toc="exclude" anchor="OP_LOCKU_IMPLEMENTATION" numbered="true"> | |||
> | <name>IMPLEMENTATION</name> | |||
<t> | <t> | |||
If the area to be unlocked does not correspond exactly to a lock | If the area to be unlocked does not correspond exactly to a lock | |||
actually held by the lock-owner, the server may return the error | actually held by the lock-owner, the server may return the error | |||
NFS4ERR_LOCK_RANGE. This includes the case in which the area is not | NFS4ERR_LOCK_RANGE. This includes the case in which the area is not | |||
locked, where the area is a sub-range of the area locked, where it | locked, where the area is a sub-range of the area locked, where it | |||
overlaps the area locked without matching exactly, or the area | overlaps the area locked without matching exactly, or the area | |||
specified includes multiple locks held by the lock-owner. In all of | specified includes multiple locks held by the lock-owner. In all of | |||
these cases, allowed by <xref target="fcntl">POSIX locking</xref> semantic s, a client receiving | these cases, allowed by <xref target="fcntl" format="default">POSIX lockin g</xref> semantics, a client receiving | |||
this error should, if it desires support for such operations, simulate | this error should, if it desires support for such operations, simulate | |||
the operation using LOCKU on ranges corresponding to locks it actually | the operation using LOCKU on ranges corresponding to locks it actually | |||
holds, possibly followed by LOCK operations for the sub-ranges not being | holds, possibly followed by LOCK operations for the sub-ranges not being | |||
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" />) to handle LOCK | (see <xref target="OP_LOCK_IMPLEMENTATION" format="default"/>) to handle L OCK | |||
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> | <section anchor="OP_LOOKUP" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 15: LOOKUP - Lookup Filename</name> | |||
$ --> | <section toc="exclude" anchor="OP_LOOKUP_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <name>ARGUMENTS</name> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <sourcecode type="xdr"><![CDATA[ | |||
<section anchor="OP_LOOKUP" title="Operation 15: LOOKUP - Lookup Filename" > | ||||
<section toc="exclude" anchor="OP_LOOKUP_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct LOOKUP4args { | struct LOOKUP4args { | |||
/* CURRENT_FH: directory */ | /* CURRENT_FH: directory */ | |||
component4 objname; | component4 objname; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LOOKUP_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_LOOKUP_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct LOOKUP4res { | struct LOOKUP4res { | |||
/* New CURRENT_FH: object */ | /* New CURRENT_FH: object */ | |||
nfsstat4 status; | nfsstat4 status; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LOOKUP_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_LOOKUP_DESCRIPTION" title="DESCRIPTION"> | ||||
<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 | |||
component and if the object exists, the current filehandle is replaced | component and if the object exists, the current filehandle is replaced | |||
with the component's filehandle. | with the component's filehandle. | |||
</t> | </t> | |||
<t> | <t> | |||
If the component cannot be evaluated either because it does not exist | If the component cannot be evaluated either because it does not exist | |||
or because the client does not have permission to evaluate the | or because the client does not have permission to evaluate the | |||
component, then an error will be returned and the current filehandle | component, then an error will be returned and the current filehandle | |||
will be unchanged. | will be unchanged. | |||
</t> | </t> | |||
<t> | <t> | |||
If the component is a zero-length string or if any component does not | If the component is a zero-length string or if any component does not | |||
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" title="IMPLEMENTATION | <section toc="exclude" anchor="OP_LOOKUP_IMPLEMENTATION" numbered="true" | |||
"> | > | |||
<t> | <name>IMPLEMENTATION</name> | |||
<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): | |||
<figure> | </t> | |||
<artwork> | <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 | GETFH]]></sourcecode> | |||
</artwork> | <t> | |||
</figure> | ||||
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 | |||
fsid attribute of the directory with the fsid attribute of the | fsid attribute of the directory with the fsid attribute of the | |||
directory looked up. If the fsids are different, then the new | directory looked up. If the fsids are different, then the new | |||
directory is a server mountpoint. UNIX clients that detect a | directory is a server mountpoint. UNIX clients that detect a | |||
mountpoint crossing will need to mount the server's file system. This | mountpoint crossing will need to mount the server's file system. This | |||
needs to be done to maintain the file object identity checking | needs to be done to maintain the file object identity checking | |||
mechanisms common to UNIX clients. | mechanisms common to UNIX clients. | |||
</t> | </t> | |||
<t> | <t> | |||
Servers that limit NFS access to "shared" or "exported" file systems | Servers that limit NFS access to "shared" or "exported" file systems | |||
should provide a pseudo file system into which the exported file systems | should provide a pseudo file system into which the exported file systems | |||
can be integrated, so that clients can browse the server's namespace. | can be integrated, so that clients can browse the server's namespace. | |||
The clients view of a pseudo file system will be limited to paths that | The clients view of a pseudo file system will be limited to paths that | |||
lead to exported file systems. | lead to exported file systems. | |||
</t> | </t> | |||
<t> | <t> | |||
Note: previous versions of the protocol assigned special semantics to | Note: previous versions of the protocol assigned special semantics to | |||
the names "." and "..". NFSv4.1 assigns no special semantics to | the names "." and "..". NFSv4.1 assigns no special semantics to | |||
these names. The LOOKUPP operator must be used to look up a parent | these names. The LOOKUPP operator must be used to look up a parent | |||
directory. | directory. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that this operation does not follow symbolic links. The client | Note that this operation does not follow symbolic links. The client | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_LOOKUPP" numbered="true" toc="default"> | |||
$ --> | <name>Operation 16: LOOKUPP - Lookup Parent Directory</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_LOOKUPP_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_LOOKUPP" title="Operation 16: LOOKUPP - Lookup Parent Direct | <sourcecode type="xdr"><![CDATA[ | |||
ory" > | ||||
<section toc="exclude" anchor="OP_LOOKUPP_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
/* CURRENT_FH: object */ | /* CURRENT_FH: object */ | |||
void; | void;]]></sourcecode> | |||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_LOOKUPP_RESULTS" numbered="true"> | |||
</section> | <name>RESULTS</name> | |||
<sourcecode type="xdr"><![CDATA[ | ||||
<section toc="exclude" anchor="OP_LOOKUPP_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct LOOKUPP4res { | struct LOOKUPP4res { | |||
/* new CURRENT_FH: parent directory */ | /* new CURRENT_FH: parent directory */ | |||
nfsstat4 status; | nfsstat4 status; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LOOKUPP_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_LOOKUPP_DESCRIPTION" title="DESCRIPTION"> | ||||
<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 | |||
filehandle for its parent directory to be the current | filehandle for its parent directory to be the current | |||
filehandle. If there is no parent directory, an NFS4ERR_NOENT | filehandle. If there is no parent directory, an NFS4ERR_NOENT | |||
error must be returned. Therefore, NFS4ERR_NOENT will be | error must be returned. Therefore, NFS4ERR_NOENT will be | |||
returned by the server when the current filehandle is at the | returned by the server when the current filehandle is at the | |||
root or top of the server's file tree. | root or top of the server's file tree. | |||
</t> | </t> | |||
<t> | <t> | |||
As is the case with LOOKUP, LOOKUPP will also cross mountpoints. | As is the case with LOOKUP, LOOKUPP will also cross mountpoints. | |||
</t> | </t> | |||
<t> | <t> | |||
If the current filehandle is not a directory or named attribute | If the current filehandle is not a directory or named attribute | |||
directory, the error NFS4ERR_NOTDIR is returned. | directory, the error NFS4ERR_NOTDIR is returned. | |||
</t> | </t> | |||
<t> | <t> | |||
If the requester's security flavor does not match that | If the requester's security flavor does not match that | |||
configured for the parent directory, then the server SHOULD | configured for the parent directory, then the server <bcp14>SHOULD</bcp14> | |||
return NFS4ERR_WRONGSEC (a future minor revision of NFSv4 may | return NFS4ERR_WRONGSEC (a future minor revision of NFSv4 may | |||
upgrade this to MUST) in the LOOKUPP response. However, if the | upgrade this to <bcp14>MUST</bcp14>) in the LOOKUPP response. However, if | |||
server does so, it MUST support the SECINFO_NO_NAME | the | |||
operation (<xref target="OP_SECINFO_NO_NAME"/>), so that the client can gr | server does so, it <bcp14>MUST</bcp14> support the SECINFO_NO_NAME | |||
acefully determine the | operation (<xref target="OP_SECINFO_NO_NAME" format="default"/>), so that | |||
the client can gracefully determine the | ||||
correct security flavor. | correct security flavor. | |||
</t> | </t> | |||
<t> | <t> | |||
If the current filehandle is a named attribute directory that is | If the current filehandle is a named attribute directory that is | |||
associated with a file system object via OPENATTR (i.e., not a | associated with a file system object via OPENATTR (i.e., not a | |||
sub-directory of a named attribute directory), LOOKUPP SHOULD | sub-directory of a named attribute directory), LOOKUPP <bcp14>SHOULD</bcp1 4> | |||
return the filehandle of the associated file system object. | return the filehandle of the associated file system object. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_LOOKUPP_IMPLEMENTATION" title="IMPLEMENTATIO | <section toc="exclude" anchor="OP_LOOKUPP_IMPLEMENTATION" numbered="true | |||
N"> | "> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
An issue to note is upward navigation from named attribute | An issue to note is upward navigation from named attribute | |||
directories. The named attribute directories are essentially | directories. The named attribute directories are essentially | |||
detached from the namespace, and this property should be safely | detached from the namespace, and this property should be safely | |||
represented in the client operating environment. LOOKUPP on a | represented in the client operating environment. LOOKUPP on a | |||
named attribute directory may return the filehandle of the | named attribute directory may return the filehandle of the | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_NVERIFY" numbered="true" toc="default"> | |||
$ --> | <name>Operation 17: NVERIFY - Verify Difference in Attributes</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_NVERIFY_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_NVERIFY" title="Operation 17: NVERIFY - Verify Difference in | <sourcecode type="xdr"><![CDATA[ | |||
Attributes" > | ||||
<section toc="exclude" anchor="OP_NVERIFY_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct NVERIFY4args { | struct NVERIFY4args { | |||
/* CURRENT_FH: object */ | /* CURRENT_FH: object */ | |||
fattr4 obj_attributes; | fattr4 obj_attributes; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_NVERIFY_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_NVERIFY_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct NVERIFY4res { | struct NVERIFY4res { | |||
nfsstat4 status; | nfsstat4 status; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_NVERIFY_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_NVERIFY_DESCRIPTION" title="DESCRIPTION"> | ||||
<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 MUST | object. If all the attributes match, then the error NFS4ERR_SAME <bcp14>M UST</bcp14> | |||
be returned. | be returned. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_NVERIFY_IMPLEMENTATION" title="IMPLEMENTATIO | <section toc="exclude" anchor="OP_NVERIFY_IMPLEMENTATION" numbered="true | |||
N"> | "> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<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: | |||
<figure> | </t> | |||
<artwork> | <sourcecode type="nfsv4compound"><![CDATA[ | |||
SEQUENCE | SEQUENCE | |||
PUTFH fh | PUTFH fh | |||
NVERIFY attrbits attrs | NVERIFY attrbits attrs | |||
READ 0 32767 | READ 0 32767]]></sourcecode> | |||
</artwork> | <t> | |||
</figure> | ||||
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> | |||
<t> | <t> | |||
In the case that a RECOMMENDED attribute is specified in the NVERIFY | In the case that a <bcp14>RECOMMENDED</bcp14> attribute is specified in th | |||
e NVERIFY | ||||
operation and the server does not support that attribute for the | operation and the server does not support that attribute for the | |||
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> | |||
<!-- $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" title="Operation 18: OPEN - Open a Regular File" > | ||||
<section toc="exclude" anchor="OP_OPEN_ARGUMENTS" title="ARGUMENTS"> | <section anchor="OP_OPEN" numbered="true" toc="default"> | |||
<figure> | <name>Operation 18: OPEN - Open a Regular File</name> | |||
<artwork> | <section toc="exclude" anchor="OP_OPEN_ARGUMENTS" numbered="true"> | |||
<name>ARGUMENTS</name> | ||||
<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 31750 ¶ | skipping to change at line 32037 ¶ | |||
* to file. Ordinary OPEN of the | * to file. Ordinary OPEN of the | |||
* specified file by current filehandle. | * specified file by current filehandle. | |||
*/ | */ | |||
case CLAIM_FH: /* new to v4.1 */ | case CLAIM_FH: /* new to v4.1 */ | |||
/* CURRENT_FH: regular file to open */ | /* CURRENT_FH: regular file to open */ | |||
void; | void; | |||
/* | /* | |||
* Like CLAIM_DELEGATE_PREV. Right to file based on a | * Like CLAIM_DELEGATE_PREV. Right to file based on a | |||
* delegation granted to a previous boot | * delegation granted to a previous boot | |||
* instance of the client. File is identified by | * instance of the client. File is identified | |||
* by filehandle. | * by filehandle. | |||
*/ | */ | |||
case CLAIM_DELEG_PREV_FH: /* new to v4.1 */ | case CLAIM_DELEG_PREV_FH: /* new to v4.1 */ | |||
/* CURRENT_FH: file being opened */ | /* CURRENT_FH: file being opened */ | |||
void; | void; | |||
/* | /* | |||
* Like CLAIM_DELEGATE_CUR. Right to file based on | * Like CLAIM_DELEGATE_CUR. Right to file based on | |||
* a delegation granted by the server. | * a delegation granted by the server. | |||
* File is identified by filehandle. | * File is identified by filehandle. | |||
skipping to change at line 31778 ¶ | skipping to change at line 32065 ¶ | |||
/* | /* | |||
* OPEN: Open a file, potentially receiving an OPEN delegation | * OPEN: Open a file, potentially receiving an OPEN delegation | |||
*/ | */ | |||
struct OPEN4args { | struct OPEN4args { | |||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_OPEN_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_OPEN_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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 31884 ¶ | skipping to change at line 32167 ¶ | |||
open_delegation4 delegation; /* Info on any open | open_delegation4 delegation; /* Info on any open | |||
delegation */ | delegation */ | |||
}; | }; | |||
union OPEN4res switch (nfsstat4 status) { | union OPEN4res switch (nfsstat4 status) { | |||
case NFS4_OK: | case NFS4_OK: | |||
/* New CURRENT_FH: opened file */ | /* New CURRENT_FH: opened file */ | |||
OPEN4resok resok4; | OPEN4resok resok4; | |||
default: | default: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_OPEN_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_OPEN_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The OPEN operation opens a regular file in a | The OPEN operation opens a regular file in a | |||
directory with the provided name or filehandle. | directory with the provided name or filehandle. | |||
OPEN can also create a file if a name is provided, | OPEN can also create a file if a name is provided, | |||
and the client specifies it wants to create a file. | and the client specifies it wants to create a file. | |||
Specification of whether or not a file is to be created, | Specification of whether or not a file is to be created, | |||
and the method of creation is via the openhow | and the method of creation is via the openhow | |||
parameter. The openhow parameter consists of | parameter. The openhow parameter consists of | |||
a switched union (data type opengflag4), which | a switched union (data type opengflag4), which | |||
switches on the value of opentype (OPEN4_NOCREATE | switches on the value of opentype (OPEN4_NOCREATE | |||
or OPEN4_CREATE). If OPEN4_CREATE is specified, | or OPEN4_CREATE). If OPEN4_CREATE is specified, | |||
this leads to another switched union (data type | this leads to another switched union (data type | |||
createhow4) that supports four cases of creation | createhow4) that supports four cases of creation | |||
methods: UNCHECKED4, GUARDED4, EXCLUSIVE4, | methods: UNCHECKED4, GUARDED4, EXCLUSIVE4, | |||
or EXCLUSIVE4_1. If opentype is OPEN4_CREATE, | or EXCLUSIVE4_1. If opentype is OPEN4_CREATE, | |||
then the claim field of the claim field | then the claim field of the claim field | |||
MUST be one of CLAIM_NULL, CLAIM_DELEGATE_CUR, or | <bcp14>MUST</bcp14> be one of CLAIM_NULL, CLAIM_DELEGATE_CUR, or | |||
CLAIM_DELEGATE_PREV, because these claim methods | CLAIM_DELEGATE_PREV, because these claim methods | |||
include a component of a file name. | include a component of a file name. | |||
</t> | </t> | |||
<t> | <t> | |||
Upon success (which might entail creation of a new | Upon success (which might entail creation of a new | |||
file), the current filehandle is replaced by that | file), the current filehandle is replaced by that | |||
of the created or existing object. | of the created or existing object. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
If the current filehandle is a named attribute | If the current filehandle is a named attribute | |||
directory, OPEN will then create or open a named | directory, OPEN will then create or open a named | |||
attribute file. Note that exclusive create | attribute file. Note that exclusive create | |||
of a named attribute is not supported. If the | of a named attribute is not supported. If the | |||
createmode is EXCLUSIVE4 or EXCLUSIVE4_1 and the | createmode is EXCLUSIVE4 or EXCLUSIVE4_1 and the | |||
current filehandle is a named attribute directory, | current filehandle is a named attribute directory, | |||
the server will return EINVAL. | the server will return EINVAL. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
UNCHECKED4 means that the file should be created if a | UNCHECKED4 means that the file should be created if a | |||
file of that name does not exist and encountering an | file of that name does not exist and encountering an | |||
existing regular file of that name is not an error. | existing regular file of that name is not an error. | |||
For this type of create, createattrs specifies the | For this type of create, createattrs specifies the | |||
initial set of attributes for the file. The set | initial set of attributes for the file. The set | |||
of attributes may include any writable attribute | of attributes may include any writable attribute | |||
valid for regular files. When an UNCHECKED4 | valid for regular files. When an UNCHECKED4 | |||
create encounters an existing file, the attributes | create encounters an existing file, the attributes | |||
specified by createattrs are not used, except that | specified by createattrs are not used, except that | |||
when createattrs specifies the size attribute | when createattrs specifies the size attribute | |||
with a size of zero, the existing file is truncated. | with a size of zero, the existing file is truncated. | |||
</t> | </t> | |||
<t> | <t> | |||
If GUARDED4 is specified, the server checks for | If GUARDED4 is specified, the server checks for | |||
the presence of a duplicate object by name before | the presence of a duplicate object by name before | |||
performing the create. If a duplicate exists, | performing the create. If a duplicate exists, | |||
NFS4ERR_EXIST is returned. | NFS4ERR_EXIST is returned. | |||
If the object does not exist, the request is | If the object does not exist, the request is | |||
performed as described for UNCHECKED4. | performed as described for UNCHECKED4. | |||
</t> | </t> | |||
<t> | <t> | |||
For the UNCHECKED4 and GUARDED4 cases, where the | For the UNCHECKED4 and GUARDED4 cases, where the | |||
operation is successful, the server will return | operation is successful, the server will return | |||
to the client an attribute mask signifying which | to the client an attribute mask signifying which | |||
attributes were successfully set for the object. | attributes were successfully set for the object. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
EXCLUSIVE4_1 and EXCLUSIVE4 | EXCLUSIVE4_1 and EXCLUSIVE4 | |||
specify that the server is to follow exclusive | specify that the server is to follow exclusive | |||
creation semantics, using the verifier to ensure | creation semantics, using the verifier to ensure | |||
exclusive creation of the target. The server should | exclusive creation of the target. The server should | |||
check for the presence of a duplicate object by name. | check for the presence of a duplicate object by name. | |||
If the object does not exist, the server creates | If the object does not exist, the server creates | |||
the object and stores the verifier with the object. | the object and stores the verifier with the object. | |||
If the object does exist and the stored verifier | If the object does exist and the stored verifier | |||
matches the client provided verifier, the server | matches the client provided verifier, the server | |||
uses the existing object as the newly created object. | uses the existing object as the newly created object. | |||
If the stored verifier does not match, then an error | If the stored verifier does not match, then an error | |||
of NFS4ERR_EXIST is returned. | of NFS4ERR_EXIST is returned. | |||
</t> | </t> | |||
<t> | <t> | |||
If using EXCLUSIVE4, and if the server uses attributes to | If using EXCLUSIVE4, and if the server uses attributes to | |||
store the exclusive create verifier, the server will signify | store the exclusive create verifier, the server will signify | |||
which attributes it used by setting the appropriate bits in | which attributes it used by setting the appropriate bits in | |||
the attribute mask that is returned in the results. | the attribute mask that is returned in the results. | |||
Unlike UNCHECKED4, GUARDED4, and EXCLUSIVE4_1, EXCLUSIVE4 does | Unlike UNCHECKED4, GUARDED4, and EXCLUSIVE4_1, EXCLUSIVE4 does | |||
not support the setting of attributes at file creation, and | not support the setting of attributes at file creation, and | |||
after a successful OPEN via EXCLUSIVE4, the client MUST | after a successful OPEN via EXCLUSIVE4, the client <bcp14>MUST</bcp14> | |||
send a SETATTR to set attributes to a known state. | send a SETATTR to set attributes to a known state. | |||
</t> | </t> | |||
<t> | <t> | |||
In NFSv4.1, EXCLUSIVE4 has been deprecated in favor | In NFSv4.1, EXCLUSIVE4 has been deprecated in favor | |||
of EXCLUSIVE4_1. | of EXCLUSIVE4_1. | |||
Unlike EXCLUSIVE4, attributes may be provided | Unlike EXCLUSIVE4, attributes may be provided | |||
in the EXCLUSIVE4_1 case, but because the server | in the EXCLUSIVE4_1 case, but because the server | |||
may use attributes of the target object to store | may use attributes of the target object to store | |||
the verifier, the set of allowable attributes | the verifier, the set of allowable attributes | |||
may be fewer than the set of attributes SETATTR | may be fewer than the set of attributes SETATTR | |||
allows. The allowable attributes for EXCLUSIVE4_1 | allows. The allowable attributes for EXCLUSIVE4_1 | |||
are indicated in the suppattr_exclcreat (<xref | are indicated in the suppattr_exclcreat (<xref target="attrdef_suppattr_ex | |||
target="attrdef_suppattr_exclcreat"/>) attribute. If the client | clcreat" format="default"/>) attribute. If the client | |||
attempts to set in cva_attrs an attribute that is not in | attempts to set in cva_attrs an attribute that is not in | |||
suppattr_exclcreat, the server MUST return NFS4ERR_INVAL. | suppattr_exclcreat, the server <bcp14>MUST</bcp14> return NFS4ERR_INVAL. | |||
The response field, attrset, indicates both which attributes | The response field, attrset, indicates both which attributes | |||
the server set from cva_attrs and which attributes the | the server set from cva_attrs and which attributes the | |||
server used to store the verifier. As described | server used to store the verifier. As described | |||
in <xref target="OP_OPEN_IMPLEMENTATION"/>, the client can compare | in <xref target="OP_OPEN_IMPLEMENTATION" format="default"/>, the client ca n compare | |||
cva_attrs.attrmask with attrset to determine which attributes | cva_attrs.attrmask with attrset to determine which attributes | |||
were used to store the verifier. | were used to store the verifier. | |||
</t> | </t> | |||
<t> | <t> | |||
With the addition of persistent sessions and | With the addition of persistent sessions and | |||
pNFS, under some conditions EXCLUSIVE4 MUST NOT | pNFS, under some conditions EXCLUSIVE4 <bcp14>MUST NOT</bcp14> | |||
be used by the client or supported by the server. | be used by the client or supported by the server. | |||
The following table summarizes the appropriate and | The following table summarizes the appropriate and | |||
mandated exclusive create methods for implementations | mandated exclusive create methods for implementations | |||
of NFSv4.1: | of NFSv4.1: | |||
</t> | </t> | |||
<table anchor="exclusive_create" align="center"> | ||||
<texttable anchor='exclusive_create'> | <name>Required Methods for Exclusive Create</name> | |||
<thead> | ||||
<preamble> | <tr> | |||
Required methods for exclusive create | <th align="left">Persistent Reply Cache Enabled</th> | |||
</preamble> | <th align="left">Server Supports pNFS</th> | |||
<th align="left">Server <bcp14>REQUIRED</bcp14></th> | ||||
<ttcol>Persistent Reply Cache Enabled</ttcol> | <th align="left">Client Allowed</th> | |||
<ttcol>Server Supports pNFS</ttcol> | </tr> | |||
<ttcol>Server REQUIRED</ttcol> <ttcol>Client Allowed</ttcol> | </thead> | |||
<tbody> | ||||
<c>no</c> <c>no</c> | <tr> | |||
<c>EXCLUSIVE4_1 and EXCLUSIVE4</c> | <td align="left">no</td> | |||
<c>EXCLUSIVE4_1 (SHOULD) or EXCLUSIVE4 (SHOULD NOT)</c> | <td align="left">no</td> | |||
<td align="left">EXCLUSIVE4_1 and EXCLUSIVE4</td> | ||||
<c>no</c> <c>yes</c> | <td align="left">EXCLUSIVE4_1 (<bcp14>SHOULD</bcp14>) or EXCLUSI | |||
<c>EXCLUSIVE4_1</c> | VE4 (<bcp14>SHOULD NOT</bcp14>)</td> | |||
<c>EXCLUSIVE4_1</c> | </tr> | |||
<tr> | ||||
<c>yes</c> <c>no</c> | <td align="left">no</td> | |||
<c>GUARDED4</c> | <td align="left">yes</td> | |||
<c>GUARDED4</c> | <td align="left">EXCLUSIVE4_1</td> | |||
<td align="left">EXCLUSIVE4_1</td> | ||||
<c>yes</c> <c>yes</c> | </tr> | |||
<c>GUARDED4</c> | <tr> | |||
<c>GUARDED4</c> | <td align="left">yes</td> | |||
<td align="left">no</td> | ||||
</texttable> | <td align="left">GUARDED4</td> | |||
<td align="left">GUARDED4</td> | ||||
<t> | </tr> | |||
<tr> | ||||
<td align="left">yes</td> | ||||
<td align="left">yes</td> | ||||
<td align="left">GUARDED4</td> | ||||
<td align="left">GUARDED4</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
<t> | ||||
If CREATE_SESSION4_FLAG_PERSIST is set in the results | If CREATE_SESSION4_FLAG_PERSIST is set in the results | |||
of CREATE_SESSION, the reply cache is persistent (see <xref target="OP_CREA TE_SESSION"/>). | of CREATE_SESSION, the reply cache is persistent (see <xref target="OP_CREA TE_SESSION" format="default"/>). | |||
If the EXCHGID4_FLAG_USE_PNFS_MDS flag is set in the | If the EXCHGID4_FLAG_USE_PNFS_MDS flag is set in the | |||
results from EXCHANGE_ID, the server is a pNFS server (see <xref target="OP _EXCHANGE_ID"/>). | results from EXCHANGE_ID, the server is a pNFS server (see <xref target="OP _EXCHANGE_ID" format="default"/>). | |||
If the client attempts to use EXCLUSIVE4 on a persistent session, | If the client attempts to use EXCLUSIVE4 on a persistent session, | |||
or a session derived from an | or a session derived from an | |||
EXCHGID4_FLAG_USE_PNFS_MDS client ID, the server MUST return | EXCHGID4_FLAG_USE_PNFS_MDS client ID, the server <bcp14>MUST</bcp14> return | |||
NFS4ERR_INVAL. | NFS4ERR_INVAL. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
With persistent sessions, exclusive create semantics | With persistent sessions, exclusive create semantics | |||
are fully achievable via GUARDED4, and so EXCLUSIVE4 | are fully achievable via GUARDED4, and so EXCLUSIVE4 | |||
or EXCLUSIVE4_1 MUST NOT be used. When pNFS is | or EXCLUSIVE4_1 <bcp14>MUST NOT</bcp14> be used. When pNFS is | |||
being used, the layout_hint attribute might | being used, the layout_hint attribute might | |||
not be supported after the file is created. Only the | not be supported after the file is created. Only the | |||
EXCLUSIVE4_1 and GUARDED methods of exclusive file | EXCLUSIVE4_1 and GUARDED methods of exclusive file | |||
creation allow the atomic setting of attributes. | creation allow the atomic setting of attributes. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
For the target directory, the server returns change_info4 information | For the target directory, the server returns change_info4 information | |||
in cinfo. With the atomic field of the change_info4 data type, the | in cinfo. With the atomic field of the change_info4 data type, the | |||
server will indicate if the before and after change attributes were | server will indicate if the before and after change attributes were | |||
obtained atomically with respect to the link creation. | obtained atomically with respect to the link creation. | |||
</t> | </t> | |||
<t> | <t> | |||
The OPEN operation provides for Windows share | The OPEN operation provides for Windows share | |||
reservation capability with the use of the | reservation capability with the use of the | |||
share_access and share_deny fields of the OPEN | share_access and share_deny fields of the OPEN | |||
arguments. The client specifies at OPEN the required | arguments. The client specifies at OPEN the required | |||
share_access and share_deny modes. For clients | share_access and share_deny modes. For clients | |||
that do not directly support SHAREs (i.e., UNIX), the | that do not directly support SHAREs (i.e., UNIX), the | |||
expected deny value is OPEN4_SHARE_DENY_NONE. In the case that | expected deny value is OPEN4_SHARE_DENY_NONE. In the case that | |||
there is an existing SHARE reservation that conflicts | there is an existing SHARE reservation that conflicts | |||
with the OPEN request, the server returns the error | with the OPEN request, the server returns the error | |||
NFS4ERR_SHARE_DENIED. For additional discussion of | NFS4ERR_SHARE_DENIED. For additional discussion of | |||
SHARE semantics, see <xref target="share_reserve" />. | SHARE semantics, see <xref target="share_reserve" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
For each OPEN, the client provides a value for | For each OPEN, the client provides a value for | |||
the owner field of the OPEN argument. The owner | the owner field of the OPEN argument. The owner | |||
field is of data type open_owner4, and contains a | field is of data type open_owner4, and contains a | |||
field called clientid and a field called owner. The | field called clientid and a field called owner. The | |||
client can set the clientid field to any value and | client can set the clientid field to any value and | |||
the server MUST ignore it. Instead, the server MUST | the server <bcp14>MUST</bcp14> ignore it. Instead, the server <bcp14>MUST </bcp14> | |||
derive the client ID from the session ID of the | derive the client ID from the session ID of the | |||
SEQUENCE operation of the COMPOUND request. | SEQUENCE operation of the COMPOUND request. | |||
</t> | </t> | |||
<t> | <t> | |||
The "seqid" field of the request is not used in | The "seqid" field of the request is not used in | |||
NFSv4.1, but it MAY be any value and the server MUST | NFSv4.1, but it <bcp14>MAY</bcp14> be any value and the server <bcp14>MUST </bcp14> | |||
ignore it. | ignore it. | |||
</t> | </t> | |||
<t> | <t> | |||
In the case that the client is recovering state from a server failure, | In the case that the client is recovering state from a server failure, | |||
the claim field of the OPEN argument is used to signify that the | the claim field of the OPEN argument is used to signify that the | |||
request is meant to reclaim state previously held. | request is meant to reclaim state previously held. | |||
</t> | </t> | |||
<t> | <t> | |||
The "claim" field of the OPEN argument is used to specify the file to | The "claim" field of the OPEN argument is used to specify the file to | |||
be opened and the state information that the client claims to | be opened and the state information that the client claims to | |||
possess. There are seven claim types as follows: | possess. There are seven claim types as follows: | |||
</t> | </t> | |||
<texttable> | <table align="center"> | |||
<ttcol align='left'>open type</ttcol> | <thead> | |||
<ttcol align='left'>description</ttcol> | <tr> | |||
<c> | <th align="left">open type</th> | |||
<th align="left">description</th> | ||||
</tr> | ||||
</thead> | ||||
<tbody> | ||||
<tr> | ||||
<td align="left"> | ||||
CLAIM_NULL, | CLAIM_NULL, | |||
CLAIM_FH | CLAIM_FH | |||
</c> | </td> | |||
<c> | <td align="left"> | |||
For the client, this is a new OPEN request and there is no | For the client, this is a new OPEN request and there is no | |||
previous state associated with the file for the client. With | previous state associated with the file for the client. With | |||
CLAIM_NULL, the file is identified by the current filehandle | CLAIM_NULL, the file is identified by the current filehandle | |||
and the specified component name. With CLAIM_FH (new to NFSv4.1), | and the specified component name. With CLAIM_FH (new to NFSv4.1), | |||
the file is identified by just the current filehandle. | the file is identified by just the current filehandle. | |||
</c> | </td> | |||
<c> | </tr> | |||
<tr> | ||||
<td align="left"> | ||||
CLAIM_PREVIOUS | CLAIM_PREVIOUS | |||
</c> | </td> | |||
<c> | <td align="left"> | |||
The client is claiming basic OPEN state for a file that was held | The client is claiming basic OPEN state for a file that was held | |||
previous to a server restart. Generally used when a server is | previous to a server restart. Generally used when a server is | |||
returning persistent filehandles; the client may not have the file | returning persistent filehandles; the client may not have the file | |||
name to reclaim the OPEN. | name to reclaim the OPEN. | |||
</c> | </td> | |||
<c> | </tr> | |||
<tr> | ||||
<td align="left"> | ||||
CLAIM_DELEGATE_CUR, | CLAIM_DELEGATE_CUR, | |||
CLAIM_DELEG_CUR_FH | CLAIM_DELEG_CUR_FH | |||
</c> | </td> | |||
<c> | <td align="left"> | |||
The client is claiming a delegation for OPEN | The client is claiming a delegation for OPEN | |||
as granted by the server. Generally, this | as granted by the server. Generally, this | |||
is done as part of recalling a delegation. With | is done as part of recalling a delegation. With | |||
CLAIM_DELEGATE_CUR, the file is identified by | CLAIM_DELEGATE_CUR, the file is identified by | |||
the current filehandle and the specified component | the current filehandle and the specified component | |||
name. With CLAIM_DELEG_CUR_FH (new to NFSv4.1), the | name. With CLAIM_DELEG_CUR_FH (new to NFSv4.1), the | |||
file is identified by just the current filehandle. | file is identified by just the current filehandle. | |||
</c> | </td> | |||
<c> | </tr> | |||
<tr> | ||||
<td align="left"> | ||||
CLAIM_DELEGATE_PREV, | CLAIM_DELEGATE_PREV, | |||
CLAIM_DELEG_PREV_FH | CLAIM_DELEG_PREV_FH | |||
</c> | </td> | |||
<c> | <td align="left"> | |||
The client is claiming a delegation granted to a | The client is claiming a delegation granted to a | |||
previous client instance; used after the client | previous client instance; used after the client | |||
restarts. The server MAY support CLAIM_DELEGATE_PREV | restarts. The server <bcp14>MAY</bcp14> support CLAIM_DELEGATE_PREV | |||
and/or CLAIM_DELEG_PREV_FH (new to NFSv4.1). If it | and/or CLAIM_DELEG_PREV_FH (new to NFSv4.1). If it | |||
does support either claim type, CREATE_SESSION MUST | does support either claim type, CREATE_SESSION <bcp14>MUST | |||
NOT remove the client's delegation state, and the | NOT</bcp14> remove the client's delegation state, and the | |||
server MUST support the DELEGPURGE operation. | server <bcp14>MUST</bcp14> support the DELEGPURGE operation. | |||
</c> | ||||
</texttable> | ||||
<t> | </td> | |||
</tr> | ||||
</tbody> | ||||
</table> | ||||
<t> | ||||
For OPEN requests that reach the server during | For OPEN requests that reach the server during | |||
the grace period, the server returns an error | the grace period, the server returns an error | |||
of NFS4ERR_GRACE. The following claim types are | of NFS4ERR_GRACE. The following claim types are | |||
exceptions: | exceptions: | |||
<list style='symbols'> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <li> | |||
OPEN requests specifying the claim type CLAIM_PREVIOUS are devoted to | OPEN requests specifying the claim type CLAIM_PREVIOUS are devoted to | |||
reclaiming opens after a server restart and are typically only | reclaiming opens after a server restart and are typically only | |||
valid during the grace period. | valid during the grace period. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
OPEN requests specifying the claim types CLAIM_DELEGATE_CUR and | OPEN requests specifying the claim types CLAIM_DELEGATE_CUR and | |||
CLAIM_DELEG_CUR_FH are valid both during and after the grace period. | CLAIM_DELEG_CUR_FH are valid both during and after the grace period. | |||
Since the granting of the delegation that they are subordinate | Since the granting of the delegation that they are subordinate | |||
to assures that there is no conflict with locks to be reclaimed | to assures that there is no conflict with locks to be reclaimed | |||
by other clients, the server need not return NFS4ERR_GRACE when | by other clients, the server need not return NFS4ERR_GRACE when | |||
these are received during the grace period. | these are received during the grace period. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
</t> | ||||
<t> | ||||
For any OPEN request, the server may return an OPEN delegation, which | For any OPEN request, the server may return an OPEN delegation, which | |||
allows further opens and closes to be handled locally on the client as | allows further opens and closes to be handled locally on the client as | |||
described in <xref target="open_delegation"/>. Note that delegation is | described in <xref target="open_delegation" format="default"/>. Note that delegation is | |||
up to the server to decide. The client should never assume that | up to the server to decide. The client should never assume that | |||
delegation will or will not be granted in a particular instance. It | delegation will or will not be granted in a particular instance. It | |||
should always be prepared for either case. A partial exception is the | should always be prepared for either case. A partial exception is the | |||
reclaim (CLAIM_PREVIOUS) case, in which a delegation type is claimed. | reclaim (CLAIM_PREVIOUS) case, in which a delegation type is claimed. | |||
In this case, delegation will always be granted, although the server | In this case, delegation will always be granted, although the server | |||
may specify an immediate recall in the delegation structure. | may specify an immediate recall in the delegation structure. | |||
</t> | </t> | |||
<t> | <t> | |||
The rflags returned by a successful OPEN allow the server to return | The rflags returned by a successful OPEN allow the server to return | |||
information governing how the open file is to be handled. | information governing how the open file is to be handled. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
OPEN4_RESULT_CONFIRM is deprecated and MUST NOT be returned | <li> | |||
OPEN4_RESULT_CONFIRM is deprecated and <bcp14>MUST NOT</bcp14> be returned | ||||
by an NFSv4.1 server. | by an NFSv4.1 server. | |||
</t> | </li> | |||
<t> | <li> | |||
OPEN4_RESULT_LOCKTYPE_POSIX indicates that the server's byte-range locking | OPEN4_RESULT_LOCKTYPE_POSIX indicates that the server's byte-range locking | |||
behavior supports the complete set of POSIX locking techniques <xref targe t="fcntl"/>. From | behavior supports the complete set of POSIX locking techniques <xref targe t="fcntl" format="default"/>. From | |||
this, the client can choose to manage byte-range locking state in a way to | this, the client can choose to manage byte-range locking state in a way to | |||
handle a mismatch of byte-range locking management. | handle a mismatch of byte-range locking management. | |||
</t> | </li> | |||
<t> | <li> | |||
OPEN4_RESULT_PRESERVE_UNLINKED indicates that the server will | OPEN4_RESULT_PRESERVE_UNLINKED indicates that the server will | |||
preserve the open file if the client (or any other client) | preserve the open file if the client (or any other client) | |||
removes the file as long as it is open. Furthermore, the | removes the file as long as it is open. Furthermore, the | |||
server promises to preserve the file through the | server promises to preserve the file through the | |||
grace period after server restart, thereby giving the client | grace period after server restart, thereby giving the client | |||
the opportunity to reclaim its open. | the opportunity to reclaim its open. | |||
</t> | </li> | |||
<t> | <li> | |||
OPEN4_RESULT_MAY_NOTIFY_LOCK indicates that the server may attempt | OPEN4_RESULT_MAY_NOTIFY_LOCK indicates that the server may attempt | |||
CB_NOTIFY_LOCK callbacks for locks on this file. This flag is a hint | CB_NOTIFY_LOCK callbacks for locks on this file. This flag is a hint | |||
only, and may be safely ignored by the client. | only, and may be safely ignored by the client. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
If the component is of zero length, NFS4ERR_INVAL will be returned. | If the component is of zero length, NFS4ERR_INVAL will be returned. | |||
The component is also subject to the normal UTF-8, character support, | The component is also subject to the normal UTF-8, character support, | |||
and name checks. See <xref target="utf8_related_errors" /> for | and name checks. See <xref target="utf8_related_errors" format="default"/ > for | |||
further discussion. | further discussion. | |||
</t> | </t> | |||
<t> | <t> | |||
When an OPEN is done and the specified open-owner already has the | When an OPEN is done and the specified open-owner already has the | |||
resulting filehandle open, the result is to "OR" together the new | resulting filehandle open, the result is to "OR" together the new | |||
share and deny status together with the existing status. In this | share and deny status together with the existing status. In this | |||
case, only a single CLOSE need be done, even though multiple OPENs | case, only a single CLOSE need be done, even though multiple OPENs | |||
were completed. When such an OPEN is done, checking of share | were completed. When such an OPEN is done, checking of share | |||
reservations for the new OPEN proceeds normally, with no exception for | reservations for the new OPEN proceeds normally, with no exception for | |||
the existing OPEN held by the same open-owner. In this case, the | the existing OPEN held by the same open-owner. In this case, the | |||
stateid returned as an "other" field that matches that of the previous | stateid returned as an "other" field that matches that of the previous | |||
open while the "seqid" field is incremented to reflect the change | open while the "seqid" field is incremented to reflect the change | |||
status due to the new open. | status due to the new open. | |||
</t> | </t> | |||
<t> | <t> | |||
If the underlying file system at the server is only accessible in a | If the underlying file system at the server is only accessible in a | |||
read-only mode and the OPEN request has specified ACCESS_WRITE or | read-only mode and the OPEN request has specified ACCESS_WRITE or | |||
ACCESS_BOTH, the server will return NFS4ERR_ROFS to indicate a | ACCESS_BOTH, the server will return NFS4ERR_ROFS to indicate a | |||
read-only file system. | read-only file system. | |||
</t> | </t> | |||
<t> | <t> | |||
As with the CREATE operation, the server MUST derive | As with the CREATE operation, the server <bcp14>MUST</bcp14> derive | |||
the owner, owner ACE, group, or group ACE if any | the owner, owner ACE, group, or group ACE if any | |||
of the four attributes are required and supported | of the four attributes are required and supported | |||
by the server's file system. For an OPEN with the | by the server's file system. For an OPEN with the | |||
EXCLUSIVE4 createmode, the server has no choice, | EXCLUSIVE4 createmode, the server has no choice, | |||
since such OPEN calls do not include the createattrs | since such OPEN calls do not include the createattrs | |||
field. Conversely, if createattrs (UNCHECKED4 or | field. Conversely, if createattrs (UNCHECKED4 or | |||
GUARDED4) or cva_attrs (EXCLUSIVE4_1) is specified, | GUARDED4) or cva_attrs (EXCLUSIVE4_1) is specified, | |||
and includes an owner, owner_group, or ACE that | and includes an owner, owner_group, or ACE that | |||
the principal in the RPC call's credentials does | the principal in the RPC call's credentials does | |||
not have authorization to create files for, then | not have authorization to create files for, then | |||
the server may return NFS4ERR_PERM. | the server may return NFS4ERR_PERM. | |||
</t> | </t> | |||
<t> | <t> | |||
In the case of an OPEN that specifies a size of zero (e.g., truncation) | In the case of an OPEN that specifies a size of zero (e.g., truncation) | |||
and the file has named attributes, the named attributes are left as | and the file has named attributes, the named attributes are left as | |||
is and are not removed. | is and are not removed. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
NFSv4.1 gives more precise control to clients over | NFSv4.1 gives more precise control to clients over | |||
acquisition of delegations via the following new | acquisition of delegations via the following new | |||
flags for the share_access field of OPEN4args: | flags for the share_access field of OPEN4args: | |||
<list style="hanging"> | </t> | |||
<t hangText="OPEN4_SHARE_ACCESS_WANT_READ_DELEG"></t> | ||||
<t hangText="OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG"></t> | <t>OPEN4_SHARE_ACCESS_WANT_READ_DELEG</t> | |||
<t hangText="OPEN4_SHARE_ACCESS_WANT_ANY_DELEG"></t> | <t>OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG</t> | |||
<t hangText="OPEN4_SHARE_ACCESS_WANT_NO_DELEG"></t> | <t>OPEN4_SHARE_ACCESS_WANT_ANY_DELEG</t> | |||
<t hangText="OPEN4_SHARE_ACCESS_WANT_CANCEL"></t> | <t>OPEN4_SHARE_ACCESS_WANT_NO_DELEG</t> | |||
<t hangText="OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL"></t> | <t>OPEN4_SHARE_ACCESS_WANT_CANCEL</t> | |||
<t hangText="OPEN4_SHARE_ACCESS_WANT_PUSH_DELEG_WHEN_UNCONTENDED"></t> | <t>OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL</t> | |||
</list> | <t>OPEN4_SHARE_ACCESS_WANT_PUSH_DELEG_WHEN_UNCONTENDED</t> | |||
</t> | ||||
<t> | <t> | |||
If (share_access & OPEN4_SHARE_ACCESS_WANT_DELEG_MASK) is | If (share_access & OPEN4_SHARE_ACCESS_WANT_DELEG_MASK) is | |||
not zero, then the client will have specified one and only one of: | not zero, then the client will have specified one and only one of: | |||
<list style="hanging"> | </t> | |||
<t hangText="OPEN4_SHARE_ACCESS_WANT_READ_DELEG"></t> | ||||
<t hangText="OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG"></t> | <t>OPEN4_SHARE_ACCESS_WANT_READ_DELEG</t> | |||
<t hangText="OPEN4_SHARE_ACCESS_WANT_ANY_DELEG"></t> | <t>OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG</t> | |||
<t hangText="OPEN4_SHARE_ACCESS_WANT_NO_DELEG"></t> | <t>OPEN4_SHARE_ACCESS_WANT_ANY_DELEG</t> | |||
<t hangText="OPEN4_SHARE_ACCESS_WANT_CANCEL"></t> | <t>OPEN4_SHARE_ACCESS_WANT_NO_DELEG</t> | |||
</list> | <t>OPEN4_SHARE_ACCESS_WANT_CANCEL</t> | |||
<t> | ||||
Otherwise, the client is neither indicating a desire nor a non-desire | Otherwise, the client is neither indicating a desire nor a non-desire | |||
for a delegation, and the server MAY or MAY not return a delegation | for a delegation, and the server <bcp14>MAY</bcp14> or | |||
<bcp14>MAY</bcp14> not return a delegation | ||||
in the OPEN response. | in the OPEN response. | |||
</t> | </t> | |||
<t> | <t> | |||
If the server supports the new _WANT_ flags and the | If the server supports the new _WANT_ flags and the | |||
client sends one or more of the new flags, | client sends one or more of the new flags, | |||
then in the event the server does not return a | then in the event the server does not return a | |||
delegation, it MUST return a delegation type of | delegation, it <bcp14>MUST</bcp14> return a delegation type of | |||
OPEN_DELEGATE_NONE_EXT. The field ond_why in the reply | OPEN_DELEGATE_NONE_EXT. The field ond_why in the reply | |||
indicates why | indicates why | |||
no delegation was returned and will be one of: | no delegation was returned and will be one of: | |||
<list style="hanging"> | </t> | |||
<t hangText="WND4_NOT_WANTED"> | ||||
<dl newline="true" spacing="normal"> | ||||
<dt>WND4_NOT_WANTED</dt> | ||||
<dd> | ||||
The client specified OPEN4_SHARE_ACCESS_WANT_NO_DELEG. | The client specified OPEN4_SHARE_ACCESS_WANT_NO_DELEG. | |||
</t> | </dd> | |||
<t hangText="WND4_CONTENTION"> | <dt>WND4_CONTENTION</dt> | |||
<dd> | ||||
There is a conflicting delegation or open on the file. | There is a conflicting delegation or open on the file. | |||
</t> | </dd> | |||
<t hangText="WND4_RESOURCE"> | <dt>WND4_RESOURCE</dt> | |||
<dd> | ||||
Resource limitations prevent the server from granting a | Resource limitations prevent the server from granting a | |||
delegation. | delegation. | |||
</t> | </dd> | |||
<t hangText="WND4_NOT_SUPP_FTYPE"> | <dt>WND4_NOT_SUPP_FTYPE</dt> | |||
<dd> | ||||
The server does not support delegations on this file type. | The server does not support delegations on this file type. | |||
</t> | </dd> | |||
<t hangText="WND4_WRITE_DELEG_NOT_SUPP_FTYPE"> | <dt>WND4_WRITE_DELEG_NOT_SUPP_FTYPE</dt> | |||
<dd> | ||||
The server does not support OPEN_DELEGATE_WRITE delegations on this fil e | The server does not support OPEN_DELEGATE_WRITE delegations on this fil e | |||
type. | type. | |||
</t> | </dd> | |||
<t hangText="WND4_NOT_SUPP_UPGRADE"> | <dt>WND4_NOT_SUPP_UPGRADE</dt> | |||
<dd> | ||||
The server does not support atomic upgrade of an OPEN_DELEGATE_READ del egation to an OPEN_DELEGATE_WRITE delegation. | The server does not support atomic upgrade of an OPEN_DELEGATE_READ del egation to an OPEN_DELEGATE_WRITE delegation. | |||
</t> | </dd> | |||
<t hangText="WND4_NOT_SUPP_DOWNGRADE"> | <dt>WND4_NOT_SUPP_DOWNGRADE</dt> | |||
<dd> | ||||
The server does not support atomic downgrade of an OPEN_DELEGATE_WRITE delegation to an OPEN_DELEGATE_READ delegation. | The server does not support atomic downgrade of an OPEN_DELEGATE_WRITE delegation to an OPEN_DELEGATE_READ delegation. | |||
</t> | </dd> | |||
<t hangText="WND4_CANCELED"> | <dt>WND4_CANCELED</dt> | |||
<dd> | ||||
The client specified OPEN4_SHARE_ACCESS_WANT_CANCEL and now | The client specified OPEN4_SHARE_ACCESS_WANT_CANCEL and now | |||
any "want" for this file object is cancelled. | any "want" for this file object is cancelled. | |||
</t> | </dd> | |||
<t hangText="WND4_IS_DIR"> | <dt>WND4_IS_DIR</dt> | |||
<dd> | ||||
The specified file object is a directory, and the operation | The specified file object is a directory, and the operation | |||
is OPEN or WANT_DELEGATION, which do not support delegations | is OPEN or WANT_DELEGATION, which do not support delegations | |||
on directories. | on directories. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | <t> | |||
<t> | ||||
OPEN4_SHARE_ACCESS_WANT_READ_DELEG, | OPEN4_SHARE_ACCESS_WANT_READ_DELEG, | |||
OPEN_SHARE_ACCESS_WANT_WRITE_DELEG, or | OPEN_SHARE_ACCESS_WANT_WRITE_DELEG, or | |||
OPEN_SHARE_ACCESS_WANT_ANY_DELEG mean, respectively, the | OPEN_SHARE_ACCESS_WANT_ANY_DELEG mean, respectively, the | |||
client wants an OPEN_DELEGATE_READ, OPEN_DELEGATE_WRITE, or any delegati on regardless which | client wants an OPEN_DELEGATE_READ, OPEN_DELEGATE_WRITE, or any delegati on regardless which | |||
of OPEN4_SHARE_ACCESS_READ, OPEN4_SHARE_ACCESS_WRITE, or | of OPEN4_SHARE_ACCESS_READ, OPEN4_SHARE_ACCESS_WRITE, or | |||
OPEN4_SHARE_ACCESS_BOTH is set. If the client has an OPEN_DELEGATE_READ delegation on a file and requests an OPEN_DELEGATE_WRITE delegation, then | OPEN4_SHARE_ACCESS_BOTH is set. If the client has an OPEN_DELEGATE_READ delegation on a file and requests an OPEN_DELEGATE_WRITE delegation, then | |||
the client is requesting atomic upgrade of its OPEN_DELEGATE_READ delega tion | the client is requesting atomic upgrade of its OPEN_DELEGATE_READ delega tion | |||
to an OPEN_DELEGATE_WRITE delegation. If the client has an OPEN_DELEGATE _WRITE delegation on | to an OPEN_DELEGATE_WRITE delegation. If the client has an OPEN_DELEGATE _WRITE delegation on | |||
a file and requests an OPEN_DELEGATE_READ delegation, then the client is | a file and requests an OPEN_DELEGATE_READ delegation, then the client is | |||
requesting atomic downgrade to an OPEN_DELEGATE_READ delegation. A serve r MAY | requesting atomic downgrade to an OPEN_DELEGATE_READ delegation. A serve r <bcp14>MAY</bcp14> | |||
support atomic upgrade or downgrade. If it does, then the | support atomic upgrade or downgrade. If it does, then the | |||
returned delegation_type of OPEN_DELEGATE_READ | returned delegation_type of OPEN_DELEGATE_READ | |||
or OPEN_DELEGATE_WRITE that is different from the delegation | or OPEN_DELEGATE_WRITE that is different from the delegation | |||
type the client currently has, indicates successful upgrade | type the client currently has, indicates successful upgrade | |||
or downgrade. If the server does not support atomic delegation upgrade o r | or downgrade. If the server does not support atomic delegation upgrade o r | |||
downgrade, then ond_why will be set to WND4_NOT_SUPP_UPGRADE or | downgrade, then ond_why will be set to WND4_NOT_SUPP_UPGRADE or | |||
WND4_NOT_SUPP_DOWNGRADE. | WND4_NOT_SUPP_DOWNGRADE. | |||
</t> | </t> | |||
<t> | <t> | |||
OPEN4_SHARE_ACCESS_WANT_NO_DELEG means that the client wants no | OPEN4_SHARE_ACCESS_WANT_NO_DELEG means that the client wants no | |||
delegation. | delegation. | |||
</t> | </t> | |||
<t> | <t> | |||
OPEN4_SHARE_ACCESS_WANT_CANCEL means that the client wants no | OPEN4_SHARE_ACCESS_WANT_CANCEL means that the client wants no | |||
delegation and wants to cancel any previously registered | delegation and wants to cancel any previously registered | |||
"want" for a delegation. | "want" for a delegation. | |||
</t> | </t> | |||
<t> | <t> | |||
The client may set one or both of | The client may set one or both of | |||
OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL and | OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL and | |||
OPEN4_SHARE_ACCESS_WANT_PUSH_DELEG_WHEN_UNCONTENDED. | OPEN4_SHARE_ACCESS_WANT_PUSH_DELEG_WHEN_UNCONTENDED. | |||
However, they will have no effect unless one of following is set: | However, they will have no effect unless one of following is set: | |||
<list style="symbols"> | </t> | |||
<t>OPEN4_SHARE_ACCESS_WANT_READ_DELEG</t> | <ul spacing="normal"> | |||
<t>OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG</t> | <li>OPEN4_SHARE_ACCESS_WANT_READ_DELEG</li> | |||
<t>OPEN4_SHARE_ACCESS_WANT_ANY_DELEG</t> | <li>OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG</li> | |||
</list> | <li>OPEN4_SHARE_ACCESS_WANT_ANY_DELEG</li> | |||
</t> | </ul> | |||
<t> | <t> | |||
If the client specifies | If the client specifies | |||
OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL, then it | OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL, then it | |||
wishes to register a "want" for a delegation, in the event the | wishes to register a "want" for a delegation, in the event the | |||
OPEN results do not include a delegation. If so and the | OPEN results do not include a delegation. If so and the | |||
server denies the delegation due to insufficient resources, | server denies the delegation due to insufficient resources, | |||
the server MAY later inform the client, via the | the server <bcp14>MAY</bcp14> later inform the client, via the | |||
CB_RECALLABLE_OBJ_AVAIL operation, that the resource | CB_RECALLABLE_OBJ_AVAIL operation, that the resource | |||
limitation condition has eased. The server will tell the | limitation condition has eased. The server will tell the | |||
client that it intends to send a future | client that it intends to send a future | |||
CB_RECALLABLE_OBJ_AVAIL operation by setting delegation_type | CB_RECALLABLE_OBJ_AVAIL operation by setting delegation_type | |||
in the results to OPEN_DELEGATE_NONE_EXT, ond_why | in the results to OPEN_DELEGATE_NONE_EXT, ond_why | |||
to WND4_RESOURCE, and ond_server_will_signal_avail set to | to WND4_RESOURCE, and ond_server_will_signal_avail set to | |||
TRUE. If | TRUE. If | |||
ond_server_will_signal_avail is set to TRUE, the server MUST | ond_server_will_signal_avail is set to TRUE, the server <bcp14>MUST</bcp 14> | |||
later send a CB_RECALLABLE_OBJ_AVAIL operation. | later send a CB_RECALLABLE_OBJ_AVAIL operation. | |||
</t> | </t> | |||
<t> | <t> | |||
If the client specifies | If the client specifies | |||
OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_UNCONTENDED, then it | OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_UNCONTENDED, then it | |||
wishes to register a "want" for a delegation, in the event the | wishes to register a "want" for a delegation, in the event the | |||
OPEN results do not include a delegation. If so and the server | OPEN results do not include a delegation. If so and the server | |||
denies the delegation due to contention, the | denies the delegation due to contention, the | |||
server MAY later inform the client, via the CB_PUSH_DELEG | server <bcp14>MAY</bcp14> later inform the client, via the CB_PUSH_DELEG | |||
operation, that the contention condition | operation, that the contention condition | |||
has eased. The server will tell the client that it intends to | has eased. The server will tell the client that it intends to | |||
send a future CB_PUSH_DELEG operation by setting | send a future CB_PUSH_DELEG operation by setting | |||
delegation_type in the results to OPEN_DELEGATE_NONE_EXT, | delegation_type in the results to OPEN_DELEGATE_NONE_EXT, | |||
ond_why to WND4_CONTENTION, and | ond_why to WND4_CONTENTION, and | |||
ond_server_will_push_deleg to TRUE. If | ond_server_will_push_deleg to TRUE. If | |||
ond_server_will_push_deleg is TRUE, the server MUST later | ond_server_will_push_deleg is TRUE, the server <bcp14>MUST</bcp14> later | |||
send a CB_PUSH_DELEG operation. | send a CB_PUSH_DELEG operation. | |||
</t> | </t> | |||
<t> | <t> | |||
If the client has previously registered a want for a | If the client has previously registered a want for a | |||
delegation on a file, and then sends a request to register a | delegation on a file, and then sends a request to register a | |||
want for a delegation on the same file, the server MUST return | want for a delegation on the same file, the server <bcp14>MUST</bcp14> r eturn | |||
a new error: NFS4ERR_DELEG_ALREADY_WANTED. If the client | a new error: NFS4ERR_DELEG_ALREADY_WANTED. If the client | |||
wishes to register a different type of delegation want for the | wishes to register a different type of delegation want for the | |||
same file, it MUST cancel the existing delegation WANT. | same file, it <bcp14>MUST</bcp14> cancel the existing delegation WANT. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_OPEN_IMPLEMENTATION" title="IMPLEMENTATION"> | <section toc="exclude" anchor="OP_OPEN_IMPLEMENTATION" numbered="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
In absence of a persistent session, the client | In absence of a persistent session, the client | |||
invokes exclusive create by setting the how parameter | invokes exclusive create by setting the how parameter | |||
to EXCLUSIVE4 or EXCLUSIVE4_1. In these cases, the | to EXCLUSIVE4 or EXCLUSIVE4_1. In these cases, the | |||
client provides a verifier that can reasonably be | client provides a verifier that can reasonably be | |||
expected to be unique. A combination of a client | expected to be unique. A combination of a client | |||
identifier, perhaps the client network address, | identifier, perhaps the client network address, | |||
and a unique number generated by the client, perhaps | and a unique number generated by the client, perhaps | |||
the RPC transaction identifier, may be appropriate. | the RPC transaction identifier, may be appropriate. | |||
</t> | </t> | |||
<t> | <t> | |||
If the object does not exist, the server creates the object and stores the | If the object does not exist, the server creates the object and stores the | |||
verifier in stable storage. For file systems that do not provide a | verifier in stable storage. For file systems that do not provide a | |||
mechanism for the storage of arbitrary file attributes, the server may | mechanism for the storage of arbitrary file attributes, the server may | |||
use one or more elements of the object's metadata to store the | use one or more elements of the object's metadata to store the | |||
verifier. The verifier MUST be stored in stable storage to prevent | verifier. The verifier <bcp14>MUST</bcp14> be stored in stable storage to prevent | |||
erroneous failure on retransmission of the request. It is assumed that | erroneous failure on retransmission of the request. It is assumed that | |||
an exclusive create is being performed because exclusive semantics are | an exclusive create is being performed because exclusive semantics are | |||
critical to the application. Because of the expected usage, exclusive | critical to the application. Because of the expected usage, exclusive | |||
CREATE does not rely solely on the server's reply cache | CREATE does not rely solely on the server's reply cache | |||
for storage of the verifier. A nonpersistent reply cache | for storage of the verifier. A nonpersistent reply cache | |||
does not survive a crash and the session and reply cache | does not survive a crash and the session and reply cache | |||
may be deleted after a network partition that exceeds the | may be deleted after a network partition that exceeds the | |||
lease time, thus opening failure windows. | lease time, thus opening failure windows. | |||
</t> | </t> | |||
<t> | <t> | |||
An NFSv4.1 server SHOULD NOT store the verifier in | An NFSv4.1 server <bcp14>SHOULD NOT</bcp14> store the verifier in | |||
any of the file's RECOMMENDED or REQUIRED attributes. | any of the file's <bcp14>RECOMMENDED</bcp14> or <bcp14>REQUIRED</bcp14> at | |||
If it does, the server SHOULD use time_modify_set or | tributes. | |||
If it does, the server <bcp14>SHOULD</bcp14> use time_modify_set or | ||||
time_access_set to store the verifier. | time_access_set to store the verifier. | |||
The server SHOULD NOT store the verifier in the | The server <bcp14>SHOULD NOT</bcp14> store the verifier in the | |||
following attributes: | following attributes: | |||
<list style="empty"> | ||||
<t>acl (it is desirable for access control to | ||||
be established at creation),</t> | ||||
<t>dacl (ditto),</t> | ||||
<t>mode (ditto),</t> | ||||
<t>owner (ditto),</t> | ||||
<t>owner_group (ditto),</t> | ||||
<t>retentevt_set (it may be desired to | ||||
establish retention at creation)</t> | ||||
<t>retention_hold (ditto),</t> | ||||
<t>retention_set (ditto),</t> | ||||
<t>sacl (it is desirable for auditing control | ||||
to be established at creation),</t> | ||||
<t>size (on some servers, size may have a | ||||
limited range of values),</t> | ||||
<t>mode_set_masked (as with mode), | ||||
<list style="empty"> | ||||
<t>and</t> | ||||
</list> | ||||
</t> | </t> | |||
<t>time_creation (a meaningful file creation | <ul empty="true" spacing="normal"> | |||
should be set when the file is created).</t> | <li>acl (it is desirable for access control to | |||
</list> | be established at creation),</li> | |||
<li>dacl (ditto),</li> | ||||
<li>mode (ditto),</li> | ||||
<li>owner (ditto),</li> | ||||
<li>owner_group (ditto),</li> | ||||
<li>retentevt_set (it may be desired to | ||||
establish retention at creation)</li> | ||||
<li>retention_hold (ditto),</li> | ||||
<li>retention_set (ditto),</li> | ||||
<li>sacl (it is desirable for auditing control | ||||
to be established at creation),</li> | ||||
<li>size (on some servers, size may have a | ||||
limited range of values),</li> | ||||
<li> | ||||
<t>mode_set_masked (as with mode), | ||||
</t> | ||||
<ul empty="true" spacing="normal"> | ||||
<li>and</li> | ||||
</ul> | ||||
</li> | ||||
<li>time_creation (a meaningful file creation | ||||
should be set when the file is created).</li> | ||||
</ul> | ||||
<t> | ||||
Another alternative for the server is to use a named attribute | Another alternative for the server is to use a named attribute | |||
to store the verifier. | to store the verifier. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
Because the EXCLUSIVE4 create method does not specify | Because the EXCLUSIVE4 create method does not specify | |||
initial attributes when processing an EXCLUSIVE4 create, | initial attributes when processing an EXCLUSIVE4 create, | |||
the server | the server | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
SHOULD set the | <li> | |||
<bcp14>SHOULD</bcp14> set the | ||||
owner of the file to that corresponding to the credential of | owner of the file to that corresponding to the credential of | |||
request's RPC header. | request's RPC header. | |||
</t> | </li> | |||
<li> | ||||
<t> | <bcp14>SHOULD NOT</bcp14> leave the file's access control to anyone | |||
SHOULD NOT leave the file's access control to anyone | ||||
but the owner of the file. | but the owner of the file. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
</t> | ||||
<t> | ||||
If the server cannot support exclusive create | If the server cannot support exclusive create | |||
semantics, possibly because of the requirement to | semantics, possibly because of the requirement to | |||
commit the verifier to stable storage, it should fail | commit the verifier to stable storage, it should fail | |||
the OPEN request with the error NFS4ERR_NOTSUPP. | the OPEN request with the error NFS4ERR_NOTSUPP. | |||
</t> | </t> | |||
<t> | <t> | |||
During an exclusive CREATE request, if the object | During an exclusive CREATE request, if the object | |||
already exists, the server reconstructs the object's | already exists, the server reconstructs the object's | |||
verifier and compares it with the verifier in | verifier and compares it with the verifier in | |||
the request. If they match, the server treats the | the request. If they match, the server treats the | |||
request as a success. The request is presumed to | request as a success. The request is presumed to | |||
be a duplicate of an earlier, successful request | be a duplicate of an earlier, successful request | |||
for which the reply was lost and that the server | for which the reply was lost and that the server | |||
duplicate request cache mechanism did not detect. If | duplicate request cache mechanism did not detect. If | |||
the verifiers do not match, the request is rejected | the verifiers do not match, the request is rejected | |||
with the status NFS4ERR_EXIST. | with the status NFS4ERR_EXIST. | |||
</t> | </t> | |||
<t> | <t> | |||
After the client has performed a successful | After the client has performed a successful | |||
exclusive create, the attrset response indicates | exclusive create, the attrset response indicates | |||
which attributes were used to store the verifier. | which attributes were used to store the verifier. | |||
If EXCLUSIVE4 was used, the attributes set in | If EXCLUSIVE4 was used, the attributes set in | |||
attrset were used for the verifier. If EXCLUSIVE4_1 | attrset were used for the verifier. If EXCLUSIVE4_1 | |||
was used, the client determines the attributes | was used, the client determines the attributes | |||
used for the verifier by comparing attrset with | used for the verifier by comparing attrset with | |||
cva_attrs.attrmask; any bits set in the former but | cva_attrs.attrmask; any bits set in the former but | |||
not the latter identify the attributes used to store | not the latter identify the attributes used to store | |||
the verifier. The client MUST immediately send a | the verifier. The client <bcp14>MUST</bcp14> immediately send a | |||
SETATTR to set attributes used to store the verifier. | SETATTR to set attributes used to store the verifier. | |||
Until it does so, the attributes used to store the | Until it does so, the attributes used to store the | |||
verifier cannot be relied upon. The subsequent | verifier cannot be relied upon. The subsequent | |||
SETATTR MUST NOT occur in the same COMPOUND request | SETATTR <bcp14>MUST NOT</bcp14> occur in the same COMPOUND request | |||
as the OPEN. | as the OPEN. | |||
</t> | </t> | |||
<t> | <t> | |||
Unless a persistent session is used, use of the | Unless a persistent session is used, use of the | |||
GUARDED4 attribute does not provide exactly once | GUARDED4 attribute does not provide exactly once | |||
semantics. In particular, if a reply is lost and | semantics. In particular, if a reply is lost and | |||
the server does not detect the retransmission of the | the server does not detect the retransmission of the | |||
request, the operation can fail with NFS4ERR_EXIST, | request, the operation can fail with NFS4ERR_EXIST, | |||
even though the create was performed successfully. | even though the create was performed successfully. | |||
The client would use this behavior in the case that | The client would use this behavior in the case that | |||
the application has not requested an exclusive create | the application has not requested an exclusive create | |||
but has asked to have the file truncated when the | but has asked to have the file truncated when the | |||
file is opened. In the case of the client timing | file is opened. In the case of the client timing | |||
out and retransmitting the create request, the client | out and retransmitting the create request, the client | |||
can use GUARDED4 to prevent against a sequence like | can use GUARDED4 to prevent against a sequence like | |||
create, write, create (retransmitted) from occurring. | create, write, create (retransmitted) from occurring. | |||
</t> | </t> | |||
<t> | <t> | |||
For SHARE reservations, the value of the expression | For SHARE reservations, the value of the expression | |||
(share_access & ~OPEN4_SHARE_ACCESS_WANT_DELEG_MASK) MUST be | (share_access & ~OPEN4_SHARE_ACCESS_WANT_DELEG_MASK) <bcp14>MUST</bcp1 4> be | |||
one of OPEN4_SHARE_ACCESS_READ, OPEN4_SHARE_ACCESS_WRITE, | one of OPEN4_SHARE_ACCESS_READ, OPEN4_SHARE_ACCESS_WRITE, | |||
or OPEN4_SHARE_ACCESS_BOTH. If not, the server MUST | or OPEN4_SHARE_ACCESS_BOTH. If not, the server <bcp14>MUST</bcp14> | |||
return NFS4ERR_INVAL. The value of share_deny MUST | return NFS4ERR_INVAL. The value of share_deny <bcp14>MUST</bcp14> | |||
be one of OPEN4_SHARE_DENY_NONE, OPEN4_SHARE_DENY_READ, | be one of OPEN4_SHARE_DENY_NONE, OPEN4_SHARE_DENY_READ, | |||
OPEN4_SHARE_DENY_WRITE, or OPEN4_SHARE_DENY_BOTH. If not, the | OPEN4_SHARE_DENY_WRITE, or OPEN4_SHARE_DENY_BOTH. If not, the | |||
server MUST return NFS4ERR_INVAL. | server <bcp14>MUST</bcp14> return NFS4ERR_INVAL. | |||
</t> | </t> | |||
<t> | <t> | |||
Based on the share_access value (OPEN4_SHARE_ACCESS_READ, | Based on the share_access value (OPEN4_SHARE_ACCESS_READ, | |||
OPEN4_SHARE_ACCESS_WRITE, or OPEN4_SHARE_ACCESS_BOTH), the client | OPEN4_SHARE_ACCESS_WRITE, or OPEN4_SHARE_ACCESS_BOTH), the client | |||
should check that the requester has the proper access rights | should check that the requester has the proper access rights | |||
to perform the specified operation. This would generally be | to perform the specified operation. This would generally be | |||
the results of applying the ACL access rules to the file for the | the results of applying the ACL access rules to the file for the | |||
current requester. However, just as with the ACCESS operation, the | current requester. However, just as with the ACCESS operation, the | |||
client should not attempt to second-guess the server's decisions, as | client should not attempt to second-guess the server's decisions, as | |||
access rights may change and may be subject to server administrative | access rights may change and may be subject to server administrative | |||
controls outside the ACL framework. If the requester's READ or | controls outside the ACL framework. If the requester's READ or | |||
WRITE operation is not authorized (depending on the share_access | WRITE operation is not authorized (depending on the share_access | |||
value), the server MUST return NFS4ERR_ACCESS. | value), the server <bcp14>MUST</bcp14> return NFS4ERR_ACCESS. | |||
</t> | ||||
<t> | </t> | |||
<t> | ||||
Note that if the client ID was not created | Note that if the client ID was not created | |||
with the EXCHGID4_FLAG_BIND_PRINC_STATEID capability set in | with the EXCHGID4_FLAG_BIND_PRINC_STATEID capability set in | |||
the reply to EXCHANGE_ID, then the server MUST | the reply to EXCHANGE_ID, then the server <bcp14>MUST | |||
NOT impose any requirement that READs and WRITEs | NOT</bcp14> impose any requirement that READs and WRITEs | |||
sent for an open file have the same credentials | sent for an open file have the same credentials | |||
as the OPEN itself, and the server is REQUIRED to | as the OPEN itself, and the server is <bcp14>REQUIRED</bcp14> to | |||
perform access checking on the READs and WRITEs | perform access checking on the READs and WRITEs | |||
themselves. Otherwise, if the reply to EXCHANGE_ID | themselves. Otherwise, if the reply to EXCHANGE_ID | |||
did have EXCHGID4_FLAG_BIND_PRINC_STATEID set, | did have EXCHGID4_FLAG_BIND_PRINC_STATEID set, | |||
then with one exception, the credentials used in the OPEN request MUST | then with one exception, the credentials used in the OPEN request <bcp14>M UST</bcp14> | |||
match those used in the READs and WRITEs, and the | match those used in the READs and WRITEs, and the | |||
stateids in the READs and WRITEs MUST match, or be | stateids in the READs and WRITEs <bcp14>MUST</bcp14> match, or be | |||
derived from the stateid from the reply to OPEN. | derived from the stateid from the reply to OPEN. | |||
The exception is if SP4_SSV or SP4_MACH_CRED state | The exception is if SP4_SSV or SP4_MACH_CRED state | |||
protection is used, and the spo_must_allow | protection is used, and the spo_must_allow | |||
result of EXCHANGE_ID includes the READ and/or WRITE | result of EXCHANGE_ID includes the READ and/or WRITE | |||
operations. In that case, the machine or SSV | operations. In that case, the machine or SSV | |||
credential will be allowed to send READ and/or WRITE. | credential will be allowed to send READ and/or WRITE. | |||
See <xref target="OP_EXCHANGE_ID"/>. | See <xref target="OP_EXCHANGE_ID" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
If the component provided to OPEN is a symbolic link, the error | If the component provided to OPEN is a symbolic link, the error | |||
NFS4ERR_SYMLINK will be returned to the client, while if it is | NFS4ERR_SYMLINK will be returned to the client, while if it is | |||
a directory the error NFS4ERR_ISDIR will be returned. | a directory the error NFS4ERR_ISDIR will be returned. | |||
If the component is neither | If the component is neither | |||
of those but not an ordinary file, the error NFS4ERR_WRONG_TYPE | of those but not an ordinary file, the error NFS4ERR_WRONG_TYPE | |||
is returned. If the current | is returned. If the current | |||
filehandle is not a directory, the error NFS4ERR_NOTDIR will be | filehandle is not a directory, the error NFS4ERR_NOTDIR will be | |||
returned. | returned. | |||
</t> | </t> | |||
<t> | <t> | |||
The use of the OPEN4_RESULT_PRESERVE_UNLINKED result flag allows | The use of the OPEN4_RESULT_PRESERVE_UNLINKED result flag allows | |||
a client to avoid the common implementation practice of renaming | a client to avoid the common implementation practice of renaming | |||
an open file to ".nfs<unique value>" after it removes the file. | an open file to ".nfs<unique value>" after it removes the file. | |||
After the server returns OPEN4_RESULT_PRESERVE_UNLINKED, if a client | After the server returns OPEN4_RESULT_PRESERVE_UNLINKED, if a client | |||
sends a REMOVE operation that would reduce the file's link count to | sends a REMOVE operation that would reduce the file's link count to | |||
zero, the server SHOULD report a value | zero, the server <bcp14>SHOULD</bcp14> report a value | |||
of zero for the numlinks attribute on the file. | of zero for the numlinks attribute on the file. | |||
</t> | </t> | |||
<t> | <t> | |||
If another client has a delegation of the file being opened that | If another client has a delegation of the file being opened that | |||
conflicts with open being done (sometimes depending on the | conflicts with open being done (sometimes depending on the | |||
share_access or share_deny value specified), | share_access or share_deny value specified), | |||
the delegation(s) MUST be recalled, and the | the delegation(s) <bcp14>MUST</bcp14> be recalled, and the | |||
operation cannot proceed until each such delegation is returned | operation cannot proceed until each such delegation is returned | |||
or revoked. Except where this | or revoked. 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 delegation remains outstanding. | returned to requests made while delegation remains outstanding. | |||
In the case of an OPEN_DELEGATE_WRITE delegation, any open by a different client | In the case of an OPEN_DELEGATE_WRITE delegation, any open by a different client | |||
will conflict, while for an OPEN_DELEGATE_READ delegation, only opens with one | will conflict, while for an OPEN_DELEGATE_READ delegation, only opens with one | |||
of the following characteristics will be considered conflicting: | of the following characteristics will be considered conflicting: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The value of share_access includes the bit | The value of share_access includes the bit | |||
OPEN4_SHARE_ACCESS_WRITE. | OPEN4_SHARE_ACCESS_WRITE. | |||
</t> | </li> | |||
<t> | <li> | |||
The value of share_deny specifies OPEN4_SHARE_DENY_READ or | The value of share_deny specifies OPEN4_SHARE_DENY_READ or | |||
OPEN4_SHARE_DENY_BOTH. | OPEN4_SHARE_DENY_BOTH. | |||
</t> | </li> | |||
<t> | <li> | |||
OPEN4_CREATE is specified together with UNCHECKED4, the | OPEN4_CREATE is specified together with UNCHECKED4, the | |||
size attribute is specified as zero (for truncation), and | size attribute is specified as zero (for truncation), and | |||
an existing file is truncated. | an existing file is truncated. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
If OPEN4_CREATE is specified and the file does not exist and | If OPEN4_CREATE is specified and the file does not exist and | |||
the current filehandle designates a directory for which another | the current filehandle designates a directory for which another | |||
client holds a directory delegation, then, unless the delegation | client holds a directory delegation, then, unless the delegation | |||
is such that the situation can be resolved by sending a notification, | is such that the situation can be resolved by sending a notification, | |||
the delegation MUST be recalled, and the operation cannot proceed | the delegation <bcp14>MUST</bcp14> be recalled, and the operation cannot p roceed | |||
until the delegation is returned or revoked. Except where this | until the delegation is returned or revoked. 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 delegation remains outstanding. | returned to requests made while delegation remains outstanding. | |||
</t> | </t> | |||
<t> | <t> | |||
If OPEN4_CREATE is specified and the file does not exist and | If OPEN4_CREATE is specified and the file does not exist and | |||
the current filehandle designates a directory for which | the current filehandle designates a directory for which | |||
one or more directory delegations exist, then, when those delegations | one or more directory delegations exist, then, when those delegations | |||
request such notifications, NOTIFY4_ADD_ENTRY will be generated | request such notifications, NOTIFY4_ADD_ENTRY will be generated | |||
as a result of this operation. | as a result of this operation. | |||
</t> | </t> | |||
<section toc="exclude" anchor="open_getfh_issue" | <section toc="exclude" anchor="open_getfh_issue" numbered="true"> | |||
title="Warning to Client Implementors"> | <name>Warning to Client Implementors</name> | |||
<t> | <t> | |||
OPEN resembles LOOKUP in that it generates a filehandle for the client | OPEN resembles LOOKUP in that it generates a filehandle for the client | |||
to use. Unlike LOOKUP though, OPEN creates server state on the | to use. Unlike LOOKUP though, OPEN creates server state on the | |||
filehandle. In normal circumstances, the client can only release this | filehandle. In normal circumstances, the client can only release this | |||
state with a CLOSE operation. CLOSE uses the current filehandle to | state with a CLOSE operation. CLOSE uses the current filehandle to | |||
determine which file to close. Therefore, the client MUST follow every | determine which file to close. Therefore, the client <bcp14>MUST</bcp14> follow every | |||
OPEN operation with a GETFH operation in the same COMPOUND procedure. | OPEN operation with a GETFH operation in the same COMPOUND procedure. | |||
This will supply the client with the filehandle such that CLOSE can be | This will supply the client with the filehandle such that CLOSE can be | |||
used appropriately. | used appropriately. | |||
</t> | </t> | |||
<t> | <t> | |||
Simply waiting for the lease on the file to expire is insufficient | Simply waiting for the lease on the file to expire is insufficient | |||
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"/>. | See also <xref target="COMPOUND_Sizing_Issues" format="default"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | ||||
</section> | </section> | |||
</section> | <section anchor="OP_OPENATTR" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 19: OPENATTR - Open Named Attribute Directory</name> | |||
$ --> | <section toc="exclude" anchor="OP_OPENATTR_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <name>ARGUMENTS</name> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <sourcecode type="xdr"><![CDATA[ | |||
<section anchor="OP_OPENATTR" title="Operation 19: OPENATTR - Open Named Attribu | ||||
te Directory" > | ||||
<section toc="exclude" anchor="OP_OPENATTR_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct OPENATTR4args { | struct OPENATTR4args { | |||
/* CURRENT_FH: object */ | /* CURRENT_FH: object */ | |||
bool createdir; | bool createdir; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_OPENATTR_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_OPENATTR_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_OPENATTR_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_OPENATTR_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The OPENATTR operation is used to obtain the filehandle of the named | The OPENATTR operation is used to obtain the filehandle of the named | |||
attribute directory associated with the current filehandle. The | attribute directory associated with the current filehandle. The | |||
result of the OPENATTR will be a filehandle to an object of type | result of the OPENATTR will be a filehandle to an object of type | |||
NF4ATTRDIR. From this filehandle, READDIR and LOOKUP operations can | NF4ATTRDIR. From this filehandle, READDIR and LOOKUP operations can | |||
be used to obtain filehandles for the various named attributes | be used to obtain filehandles for the various named attributes | |||
associated with the original file system object. Filehandles returned | associated with the original file system object. Filehandles returned | |||
within the named attribute directory will designate objects of | within the named attribute directory will designate objects of | |||
type of NF4NAMEDATTR. | type of NF4NAMEDATTR. | |||
</t> | </t> | |||
<t> | <t> | |||
The createdir argument allows the client to signify if a named | The createdir argument allows the client to signify if a named | |||
attribute directory should be created as a result of the OPENATTR | attribute directory should be created as a result of the OPENATTR | |||
operation. Some clients may use the OPENATTR operation with a value | operation. Some clients may use the OPENATTR operation with a value | |||
of FALSE for createdir to determine if any named attributes exist for | of FALSE for createdir to determine if any named attributes exist for | |||
the object. If none exist, then NFS4ERR_NOENT will be returned. If | the object. If none exist, then NFS4ERR_NOENT will be returned. If | |||
createdir has a value of TRUE and no named attribute directory exists, | createdir has a value of TRUE and no named attribute directory exists, | |||
one is created and its filehandle becomes the current filehandle. | one is created and its filehandle becomes the current filehandle. | |||
On the other hand, if createdir has a value of TRUE and the named | On the other hand, if createdir has a value of TRUE and the named | |||
attribute directory already exists, no error results and the filehandle | attribute directory already exists, no error results and the filehandle | |||
of the existing directory becomes the current filehandle. The | of the existing directory becomes the current filehandle. The | |||
creation of a named attribute directory assumes | creation of a named attribute directory assumes | |||
that the server has implemented named attribute support in this | that the server has implemented named attribute support in this | |||
fashion and is not required to do so by this definition. | fashion and is not required to do so by this definition. | |||
</t> | </t> | |||
<t> | <t> | |||
If the current file handle designates an object of type | If the current filehandle designates an object of type | |||
NF4NAMEDATTR (a named attribute) or NF4ATTRDIR (a named attribute | NF4NAMEDATTR (a named attribute) or NF4ATTRDIR (a named attribute | |||
directory), an error of NFS4ERR_WRONG_TYPE is returned to the | directory), an error of NFS4ERR_WRONG_TYPE is returned to the | |||
client. Named attributes or a named attribute directory MUST NOT | client. Named attributes or a named attribute directory <bcp14>MUST NOT</ bcp14> | |||
have their own named attributes. | have their own named attributes. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_OPENATTR_IMPLEMENTATION" title="IMPLEMENTATI | <section toc="exclude" anchor="OP_OPENATTR_IMPLEMENTATION" numbered="tru | |||
ON"> | e"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_OPEN_DOWNGRADE" numbered="true" toc="default"> | |||
$ --> | <name>Operation 21: OPEN_DOWNGRADE - Reduce Open File Access</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_OPEN_DOWNGRADE_ARGUMENTS" numbered="tr | |||
<!-- Copyright (C) The Internet Society (2006) --> | ue"> | |||
<section anchor="OP_OPEN_DOWNGRADE" title="Operation 21: OPEN_DOWNGRADE - Reduce | <name>ARGUMENTS</name> | |||
Open File Access" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_OPEN_DOWNGRADE_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_OPEN_DOWNGRADE_RESULTS" numbered="true | |||
</figure> | "> | |||
</section> | <name>RESULTS</name> | |||
<sourcecode type="xdr"><![CDATA[ | ||||
<section toc="exclude" anchor="OP_OPEN_DOWNGRADE_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_OPEN_DOWNGRADE_DESCRIPTION" numbered=" | |||
</figure> | true"> | |||
</section> | <name>DESCRIPTION</name> | |||
<t> | ||||
<section toc="exclude" anchor="OP_OPEN_DOWNGRADE_DESCRIPTION" title="DESCRIPTI | ||||
ON"> | ||||
<t> | ||||
This operation is used to adjust the access and deny states | This operation is used to adjust the access and deny states | |||
for a given open. This is necessary when a given open-owner opens the | for a given open. This is necessary when a given open-owner opens the | |||
same file multiple times with different access and deny | same file multiple times with different access and deny | |||
values. In this situation, a close of one of the opens may change the | values. In this situation, a close of one of the opens may change the | |||
appropriate share_access and share_deny flags to remove bits | appropriate share_access and share_deny flags to remove bits | |||
associated with opens no longer in effect. | associated with opens no longer in effect. | |||
</t> | </t> | |||
<t> | <t> | |||
Valid values for the expression (share_access & | Valid values for the expression (share_access & | |||
~OPEN4_SHARE_ACCESS_WANT_DELEG_MASK) are OPEN4_SHARE_ACCESS_READ, | ~OPEN4_SHARE_ACCESS_WANT_DELEG_MASK) are OPEN4_SHARE_ACCESS_READ, | |||
OPEN4_SHARE_ACCESS_WRITE, or OPEN4_SHARE_ACCESS_BOTH. If the client | OPEN4_SHARE_ACCESS_WRITE, or OPEN4_SHARE_ACCESS_BOTH. If the client | |||
specifies other values, the server MUST reply with NFS4ERR_INVAL. | specifies other values, the server <bcp14>MUST</bcp14> reply with NFS4ERR_ | |||
INVAL. | ||||
</t> | ||||
<t> | </t> | |||
<t> | ||||
Valid values for the share_deny field are | Valid values for the share_deny field are | |||
OPEN4_SHARE_DENY_NONE, OPEN4_SHARE_DENY_READ, | OPEN4_SHARE_DENY_NONE, OPEN4_SHARE_DENY_READ, | |||
OPEN4_SHARE_DENY_WRITE, or OPEN4_SHARE_DENY_BOTH. If | OPEN4_SHARE_DENY_WRITE, or OPEN4_SHARE_DENY_BOTH. If | |||
the client specifies other values, the server MUST | the client specifies other values, the server <bcp14>MUST</bcp14> | |||
reply with NFS4ERR_INVAL. | reply with NFS4ERR_INVAL. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
After checking for valid values of share_access and | After checking for valid values of share_access and | |||
share_deny, the server replaces the current access | share_deny, the server replaces the current access | |||
and deny modes on the file with share_access and | and deny modes on the file with share_access and | |||
share_deny subject to the following constraints: | share_deny subject to the following constraints: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
The bits in share_access SHOULD equal the union of the share_access | <li> | |||
The bits in share_access <bcp14>SHOULD</bcp14> equal the union of the sha | ||||
re_access | ||||
bits (not including OPEN4_SHARE_WANT_* bits) | bits (not including OPEN4_SHARE_WANT_* bits) | |||
specified for some subset of the OPENs | specified for some subset of the OPENs | |||
in effect for the current open-owner on the current | in effect for the current open-owner on the current | |||
file. | file. | |||
</t> | </li> | |||
<li> | ||||
<t> | The bits in share_deny <bcp14>SHOULD</bcp14> equal the union of the | |||
The bits in share_deny SHOULD equal the union of the | ||||
share_deny bits specified for some subset | share_deny bits specified for some subset | |||
of the OPENs in effect for the current open-owner | of the OPENs in effect for the current open-owner | |||
on the current file. | on the current file. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
If the above constraints are not respected, | If the above constraints are not respected, | |||
the server SHOULD return the error NFS4ERR_INVAL. | the server <bcp14>SHOULD</bcp14> return the error NFS4ERR_INVAL. | |||
Since share_access and share_deny bits should be | Since share_access and share_deny bits should be | |||
subsets of those already granted, short of a defect | subsets of those already granted, short of a defect | |||
in the client or server implementation, it is not | in the client or server implementation, it is not | |||
possible for the OPEN_DOWNGRADE request to be denied | possible for the OPEN_DOWNGRADE request to be denied | |||
because of conflicting share reservations. | because of conflicting share reservations. | |||
</t> | </t> | |||
<t> | ||||
<t> | The seqid argument is not used in NFSv4.1, <bcp14>MAY</bcp14> be any value | |||
The seqid argument is not used in NFSv4.1, MAY be any value, and | , and | |||
MUST be ignored by the server. | <bcp14>MUST</bcp14> be ignored by the server. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_OPEN_DOWNGRADE_IMPLEMENTATION" title="IMPLEM | <section toc="exclude" anchor="OP_OPEN_DOWNGRADE_IMPLEMENTATION" numbere | |||
ENTATION"> | d="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
An OPEN_DOWNGRADE operation may make OPEN_DELEGATE_READ delegations granta ble | An OPEN_DOWNGRADE operation may make OPEN_DELEGATE_READ delegations granta ble | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_PUTFH" numbered="true" toc="default"> | |||
$ --> | <name>Operation 22: PUTFH - Set Current Filehandle</name> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <section toc="exclude" anchor="OP_PUTFH_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_PUTFH" title="Operation 22: PUTFH - Set Current Filehandle" | <sourcecode type="xdr"><![CDATA[ | |||
> | ||||
<section toc="exclude" anchor="OP_PUTFH_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct PUTFH4args { | struct PUTFH4args { | |||
nfs_fh4 object; | nfs_fh4 object; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_PUTFH_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_PUTFH_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_PUTFH_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_PUTFH_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
This operation replaces the current filehandle with the filehandle provide d as an | This operation replaces the current filehandle with the filehandle provide d as an | |||
argument. It clears the current stateid. | argument. It clears the current stateid. | |||
</t> | </t> | |||
<t> | <t> | |||
If the security mechanism used by the requester does not meet the | If the security mechanism used by the requester does not meet the | |||
requirements of the filehandle provided to this operation, the server | requirements of the filehandle provided to this operation, the server | |||
MUST return NFS4ERR_WRONGSEC. | <bcp14>MUST</bcp14> return NFS4ERR_WRONGSEC. | |||
</t> | </t> | |||
<t> | <t> | |||
See <xref target="current_filehandle"/> for more details on the | See <xref target="current_filehandle" format="default"/> for more details | |||
on the | ||||
current filehandle. | current filehandle. | |||
</t> | </t> | |||
<t> | <t> | |||
See <xref target="current_stateid"/> 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_PUTFH_IMPLEMENTATION" title="IMPLEMENTATION" | <section toc="exclude" anchor="OP_PUTFH_IMPLEMENTATION" numbered="true"> | |||
> | <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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_PUTPUBFH" numbered="true" toc="default"> | |||
$ --> | <name>Operation 23: PUTPUBFH - Set Public Filehandle</name> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <section toc="exclude" anchor="OP_PUTPUBFH_ARGUMENT" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENT</name> | |||
<section anchor="OP_PUTPUBFH" title="Operation 23: PUTPUBFH - Set | <sourcecode type="xdr"><![CDATA[ | |||
Public Filehandle" > | ||||
<section toc="exclude" anchor="OP_PUTPUBFH_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
void; | void; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_PUTPUBFH_RESULT" numbered="true"> | |||
<section toc="exclude" anchor="OP_PUTPUBFH_RESULT" title="RESULT"> | <name>RESULT</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_PUTPUBFH_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_PUTPUBFH_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
This operation replaces the current filehandle with the filehandle that | This operation replaces the current filehandle with the filehandle that | |||
represents the public filehandle of the server's namespace. | represents the public filehandle of the server's namespace. | |||
This filehandle may be different from the "root" filehandle | This filehandle may be different from the "root" filehandle | |||
that may be associated with some other directory on the server. | that may be associated with some other directory on the server. | |||
</t> | </t> | |||
<t> | <t> | |||
PUTPUBFH also clears the current stateid. | PUTPUBFH also clears the current stateid. | |||
</t> | </t> | |||
<t> | <t> | |||
The public filehandle represents the concepts embodied in <xref | The public filehandle represents the concepts embodied in <xref target="RF | |||
target="RFC2054">RFC 2054</xref>, <xref | C2054" format="default">RFC 2054</xref>, <xref target="RFC2055" format="default" | |||
target="RFC2055">RFC 2055</xref>, and <xref | >RFC 2055</xref>, and <xref target="RFC2224" format="default">RFC 2224</xref>. | |||
target="RFC2224">RFC 2224</xref>. The intent for NFSv4.1 | The intent for NFSv4.1 | |||
is that the public filehandle (represented by the PUTPUBFH | is that the public filehandle (represented by the PUTPUBFH | |||
operation) be used as a method of providing WebNFS server | operation) be used as a method of providing WebNFS server | |||
compatibility with NFSv3. | compatibility with NFSv3. | |||
</t> | </t> | |||
<t> | <t> | |||
The public filehandle and the root filehandle (represented by the | The public filehandle and the root filehandle (represented by the | |||
PUTROOTFH operation) SHOULD be equivalent. If the public and root | PUTROOTFH operation) <bcp14>SHOULD</bcp14> be equivalent. If the public a | |||
filehandles are not equivalent, then the directory corresponding to the pu | nd root | |||
blic filehandle MUST be a | filehandles are not equivalent, then the directory corresponding to the pu | |||
blic filehandle <bcp14>MUST</bcp14> be a | ||||
descendant of the directory corresponding to the root filehandle. | descendant of the directory corresponding to the root filehandle. | |||
</t> | </t> | |||
<t> | <t> | |||
See <xref target="current_filehandle"/> for more details on the | See <xref target="current_filehandle" format="default"/> for more details | |||
on the | ||||
current filehandle. | current filehandle. | |||
</t> | </t> | |||
<t> | <t> | |||
See <xref target="current_stateid"/> 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_PUTPUBFH_IMPLEMENTATION" title="IMPLEMENTATI | <section toc="exclude" anchor="OP_PUTPUBFH_IMPLEMENTATION" numbered="tru | |||
ON"> | e"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<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> | |||
<t> | <t> | |||
With the NFSv3 public filehandle, the client is | With the NFSv3 public filehandle, the client is | |||
able to specify whether the pathname provided in the LOOKUP | able to specify whether the pathname provided in the LOOKUP | |||
should be evaluated as either an absolute path relative to the | should be evaluated as either an absolute path relative to the | |||
server's root or relative to the public filehandle. <xref | server's root or relative to the public filehandle. <xref target="RFC2224 | |||
target="RFC2224">RFC 2224</xref> contains further discussion of | " format="default">RFC 2224</xref> contains further discussion of | |||
the functionality. With NFSv4.1, that type of | the functionality. With NFSv4.1, that type of | |||
specification is not directly available in the LOOKUP operation. | specification is not directly available in the LOOKUP operation. | |||
The reason for this is because the component separators needed | The reason for this is because the component separators needed | |||
to specify absolute vs. relative are not allowed in NFSv4. Therefore, the client is responsible for constructing its | to specify absolute vs. relative are not allowed in NFSv4. Therefore, the client is responsible for constructing its | |||
request such that the use of either PUTROOTFH or PUTPUBFH | request such that the use of either PUTROOTFH or PUTPUBFH | |||
signifies absolute or relative evaluation of an NFS URL, | signifies absolute or relative evaluation of an NFS URL, | |||
respectively. | respectively. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that there are warnings mentioned in <xref | Note that there are warnings mentioned in <xref target="RFC2224" format="d | |||
target="RFC2224">RFC 2224</xref> with respect to the use of | efault">RFC 2224</xref> with respect to the use of | |||
absolute evaluation and the restrictions the server may place on | absolute evaluation and the restrictions the server may place on | |||
that evaluation with respect to how much of its namespace has | that evaluation with respect to how much of its namespace has | |||
been made available. These same warnings apply to NFSv4.1. It is likely, therefore, that because of server | been made available. These same warnings apply to NFSv4.1. It is likely, therefore, that because of server | |||
implementation details, an NFSv3 absolute public | implementation details, an NFSv3 absolute public | |||
filehandle look up may behave differently than an NFSv4.1 | filehandle look up may behave differently than an NFSv4.1 | |||
absolute resolution. | absolute resolution. | |||
</t> | </t> | |||
<t> | <t> | |||
There is a form of security negotiation as described | There is a form of security negotiation as described | |||
in <xref target="RFC2755">RFC 2755</xref> that uses | in <xref target="RFC2755" format="default">RFC 2755</xref> that uses | |||
the public filehandle and an overloading of the pathname. | the public filehandle and an overloading of the pathname. | |||
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" />. | <xref target="Security_Service_Negotiation" format="default"/>. | |||
</t> | ||||
</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="OP_PUTROOTFH" title="Operation 24: PUTROOTFH - Set Root Filehan | ||||
dle" > | ||||
<section toc="exclude" anchor="OP_PUTROOTFH_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
void; | ||||
</artwork> | ||||
</figure> | ||||
</section> | ||||
<section toc="exclude" anchor="OP_PUTROOTFH_RESULTS" title="RESULTS"> | </t> | |||
<figure> | </section> | |||
<artwork> | </section> | |||
<section anchor="OP_PUTROOTFH" numbered="true" toc="default"> | ||||
<name>Operation 24: PUTROOTFH - Set Root Filehandle</name> | ||||
<section toc="exclude" anchor="OP_PUTROOTFH_ARGUMENTS" numbered="true"> | ||||
<name>ARGUMENTS</name> | ||||
<sourcecode type="xdr"><![CDATA[ | ||||
void;]]></sourcecode> | ||||
</section> | ||||
<section toc="exclude" anchor="OP_PUTROOTFH_RESULTS" numbered="true"> | ||||
<name>RESULTS</name> | ||||
<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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_PUTROOTFH_DESCRIPTION" numbered="true" | |||
</figure> | > | |||
</section> | <name>DESCRIPTION</name> | |||
<t> | ||||
<section toc="exclude" anchor="OP_PUTROOTFH_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
This operation replaces the current filehandle with the filehandle that re presents | This operation replaces the current filehandle with the filehandle that re presents | |||
the root of the server's namespace. From this filehandle, a LOOKUP | the root of the server's namespace. From this filehandle, a LOOKUP | |||
operation can locate any other filehandle on the server. This | operation can locate any other filehandle on the server. This | |||
filehandle may be different from the "public" filehandle that may be | filehandle may be different from the "public" filehandle that may be | |||
associated with some other directory on the server. | associated with some other directory on the server. | |||
</t> | </t> | |||
<t> | <t> | |||
PUTROOTFH also clears the current stateid. | PUTROOTFH also clears the current stateid. | |||
</t> | </t> | |||
<t> | <t> | |||
See <xref target="current_filehandle"/> for more details on the | See <xref target="current_filehandle" format="default"/> for more details | |||
on the | ||||
current filehandle. | current filehandle. | |||
</t> | </t> | |||
<t> | <t> | |||
See <xref target="current_stateid"/> 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_PUTROOTFH_IMPLEMENTATION" title="IMPLEMENTAT | <section toc="exclude" anchor="OP_PUTROOTFH_IMPLEMENTATION" numbered="tr | |||
ION"> | ue"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_READ" numbered="true" toc="default"> | |||
$ --> | <name>Operation 25: READ - Read from File</name> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <section toc="exclude" anchor="OP_READ_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_READ" title="Operation 25: READ - Read from File" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_READ_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct READ4args { | struct READ4args { | |||
/* CURRENT_FH: file */ | /* CURRENT_FH: file */ | |||
stateid4 stateid; | stateid4 stateid; | |||
offset4 offset; | offset4 offset; | |||
count4 count; | count4 count; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_READ_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_READ_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_READ_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_READ_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The READ operation reads data from the regular file identified by the | The READ operation reads data from the regular file identified by the | |||
current filehandle. | current filehandle. | |||
</t> | </t> | |||
<t> | <t> | |||
The client provides an offset of where the READ is to start and a | The client provides an offset of where the READ is to start and a | |||
count of how many bytes are to be read. An offset of zero means | count of how many bytes are to be read. An offset of zero means | |||
to read data starting at the beginning of the file. If offset is | to read data starting at the beginning of the file. If offset is | |||
greater than or equal to the size of the file, the status NFS4_OK is | greater than or equal to the size of the file, the status NFS4_OK is | |||
returned with a data length set to zero and eof is set to TRUE. | returned with a data length set to zero and eof is set to TRUE. | |||
The READ is subject to access permissions checking. | The READ is subject to access permissions checking. | |||
</t> | </t> | |||
<t> | <t> | |||
If the client specifies a count value of zero, the READ succeeds | If the client specifies a count value of zero, the READ succeeds | |||
and returns zero bytes of data again subject to access permissions | and returns zero bytes of data again subject to access permissions | |||
checking. The server may choose to return fewer bytes than specified | checking. The server may choose to return fewer bytes than specified | |||
by the client. The client needs to check for this condition and | by the client. The client needs to check for this condition and | |||
handle the condition appropriately. | handle the condition appropriately. | |||
</t> | </t> | |||
<t> | <t> | |||
Except when special stateids are used, the | Except when special stateids are used, the | |||
stateid value for a READ request represents a value returned from | stateid value for a READ request represents a value returned from | |||
a previous byte-range lock or share reservation request or the stateid | a previous byte-range lock or share reservation request or the stateid | |||
associated with a delegation. The stateid identifies the associated | associated with a delegation. The stateid identifies the associated | |||
owners if any and is | owners if any and is | |||
used by the server to verify that the associated locks are still | used by the server to verify that the associated locks are still | |||
valid (e.g., have not been revoked). | valid (e.g., have not been revoked). | |||
</t> | </t> | |||
<t> | <t> | |||
If the read ended at the end-of-file (formally, in a correctly formed | If the read ended at the end-of-file (formally, in a correctly formed | |||
READ operation, if offset + count is equal to the size of the file), or | READ operation, if offset + count is equal to the size of the file), or | |||
the READ operation extends beyond the size of the file (if offset + | the READ operation extends beyond the size of the file (if offset + | |||
count is greater than the size of the file), eof is returned as TRUE; | count is greater than the size of the file), eof is returned as TRUE; | |||
otherwise, it is FALSE. A successful READ of an empty file will always | otherwise, it is FALSE. A successful READ of an empty file will always | |||
return eof as TRUE. | return eof as TRUE. | |||
</t> | </t> | |||
<t> | <t> | |||
If the current filehandle is not an ordinary file, an error will be | If the current filehandle is not an ordinary file, an error will be | |||
returned to the client. In the case that the current filehandle | returned to the client. In the case that the current filehandle | |||
represents an object of type NF4DIR, NFS4ERR_ISDIR is returned. | represents an object of type NF4DIR, NFS4ERR_ISDIR is returned. | |||
If the current filehandle designates a symbolic link, | If the current filehandle designates a symbolic link, | |||
NFS4ERR_SYMLINK is returned. In all other cases, | NFS4ERR_SYMLINK is returned. In all other cases, | |||
NFS4ERR_WRONG_TYPE is returned. | NFS4ERR_WRONG_TYPE is returned. | |||
</t> | </t> | |||
<t> | <t> | |||
For a READ with a stateid value of all bits equal to zero, the server MAY | For a READ with a stateid value of all bits equal to zero, the server <bcp | |||
allow | 14>MAY</bcp14> allow | |||
the READ to be serviced subject to mandatory byte-range locks or the curre nt | the READ to be serviced subject to mandatory byte-range locks or the curre nt | |||
share deny modes for the file. For a READ with a stateid value of all | share deny modes for the file. For a READ with a stateid value of all | |||
bits equal to one, the server MAY allow READ operations to bypass locking checks | bits equal to one, the server <bcp14>MAY</bcp14> allow READ operations to bypass locking checks | |||
at the server. | at the server. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_READ_IMPLEMENTATION" title="IMPLEMENTATION"> | <section toc="exclude" anchor="OP_READ_IMPLEMENTATION" numbered="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
If the server returns a "short read" (i.e., fewer data than requested and eof is set to FALSE), the client should send another READ to get the | If the server returns a "short read" (i.e., fewer data than requested and eof is set to FALSE), the client should send another READ to get the | |||
remaining data. A server may return less data than requested under | remaining data. A server may return less data than requested under | |||
several circumstances. The file may have been truncated by another | several circumstances. The file may have been truncated by another | |||
client or perhaps on the server itself, changing the file size from | client or perhaps on the server itself, changing the file size from | |||
what the requesting client believes to be the case. This would reduce | what the requesting client believes to be the case. This would reduce | |||
the actual amount of data available to the client. It is possible | the actual amount of data available to the client. It is possible | |||
that the server reduce the transfer size and so return a short | that the server reduce the transfer size and so return a short | |||
read result. Server resource exhaustion may also occur in a | read result. Server resource exhaustion may also occur in a | |||
short read. | short read. | |||
</t> | </t> | |||
<t> | <t> | |||
If mandatory byte-range locking is in effect for the file, and if the byte -range | If mandatory byte-range locking is in effect for the file, and if the byte -range | |||
corresponding to the data to be read from the file is WRITE_LT locked by a n | corresponding to the data to be read from the file is WRITE_LT locked by a n | |||
owner not associated with the stateid, the server will return the | owner not associated with the stateid, the server will return the | |||
NFS4ERR_LOCKED error. The client should try to get the appropriate | NFS4ERR_LOCKED error. The client should try to get the appropriate | |||
READ_LT via the LOCK operation before re-attempting the | READ_LT via the LOCK operation before re-attempting the | |||
READ. When the READ completes, the client should release the byte-range | READ. When the READ completes, the client should release the byte-range | |||
lock via LOCKU. | lock via LOCKU. | |||
</t> | </t> | |||
<t> | <t> | |||
If another client has an OPEN_DELEGATE_WRITE delegation for the file being read, | If another client has an OPEN_DELEGATE_WRITE delegation for the file being read, | |||
the delegation must be recalled, and the | the delegation must be recalled, and the | |||
operation cannot proceed until that delegation is returned | operation cannot proceed until that delegation is returned | |||
or revoked. Except where this | or revoked. 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. | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_READDIR" numbered="true" toc="default"> | |||
$ --> | <name>Operation 26: READDIR - Read Directory</name> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <section toc="exclude" anchor="OP_READDIR_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_READDIR" title="Operation 26: READDIR - Read Directory" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_READDIR_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_READDIR_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_READDIR_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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 33295 ¶ | skipping to change at line 33522 ¶ | |||
struct READDIR4resok { | struct READDIR4resok { | |||
verifier4 cookieverf; | verifier4 cookieverf; | |||
dirlist4 reply; | dirlist4 reply; | |||
}; | }; | |||
union READDIR4res switch (nfsstat4 status) { | union READDIR4res switch (nfsstat4 status) { | |||
case NFS4_OK: | case NFS4_OK: | |||
READDIR4resok resok4; | READDIR4resok resok4; | |||
default: | default: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_READDIR_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_READDIR_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The READDIR operation retrieves a variable number of entries from a | The READDIR operation retrieves a variable number of entries from a | |||
file system directory and returns client-requested attributes for each | file system directory and returns client-requested attributes for each | |||
entry along with information to allow the client to request additional | entry along with information to allow the client to request additional | |||
directory entries in a subsequent READDIR. | directory entries in a subsequent READDIR. | |||
</t> | </t> | |||
<t> | <t> | |||
The arguments contain a cookie value that represents where the READDIR | The arguments contain a cookie value that represents where the READDIR | |||
should start within the directory. A value of zero for the cookie | should start within the directory. A value of zero for the cookie | |||
is used to start reading at the beginning of the directory. For | is used to start reading at the beginning of the directory. For | |||
subsequent READDIR requests, the client specifies a cookie value that | subsequent READDIR requests, the client specifies a cookie value that | |||
is provided by the server on a previous READDIR request. | is provided by the server on a previous READDIR request. | |||
</t> | </t> | |||
<t> | <t> | |||
The request's cookieverf field should be set to 0 | The request's cookieverf field should be set to 0 | |||
zero) when the request's cookie field is zero | zero) when the request's cookie field is zero | |||
(first read of the directory). On subsequent requests, the | (first read of the directory). On subsequent requests, the | |||
cookieverf field must match the cookieverf returned | cookieverf field must match the cookieverf returned | |||
by the READDIR in which the cookie was acquired. | by the READDIR in which the cookie was acquired. | |||
If the server determines that the cookieverf | If the server determines that the cookieverf | |||
is no longer valid for the directory, the error | is no longer valid for the directory, the error | |||
NFS4ERR_NOT_SAME must be returned. | NFS4ERR_NOT_SAME must be returned. | |||
</t> | </t> | |||
<t> | <t> | |||
The dircount field of the request is a hint of the maximum number | The dircount field of the request is a hint of the maximum number | |||
of bytes of directory information that should be returned. This value | of bytes of directory information that should be returned. This value | |||
represents the total length of the names of the directory entries and the | represents the total length of the names of the directory entries and the | |||
cookie value for these entries. This length represents the XDR | cookie value for these entries. This length represents the XDR | |||
encoding of the data (names and cookies) and not the length in the | encoding of the data (names and cookies) and not the length in the | |||
native format of the server. | native format of the server. | |||
</t> | </t> | |||
<t> | <t> | |||
The maxcount field of the request represents the maximum | The maxcount field of the request represents the maximum | |||
total size of all of the data being returned within | total size of all of the data being returned within | |||
the READDIR4resok structure and includes the XDR | the READDIR4resok structure and includes the XDR | |||
overhead. The server MAY return less data. If the | overhead. The server <bcp14>MAY</bcp14> return less data. If the | |||
server is unable to return a single directory entry | server is unable to return a single directory entry | |||
within the maxcount limit, the error NFS4ERR_TOOSMALL | within the maxcount limit, the error NFS4ERR_TOOSMALL | |||
MUST be returned to the client. | <bcp14>MUST</bcp14> be returned to the client. | |||
</t> | </t> | |||
<t> | <t> | |||
Finally, the request's attr_request field represents | Finally, the request's attr_request field represents | |||
the list of attributes to be returned for each | the list of attributes to be returned for each | |||
directory entry supplied by the server. | directory entry supplied by the server. | |||
</t> | </t> | |||
<t> | <t> | |||
A successful reply consists of a list of | A successful reply consists of a list of | |||
directory entries. Each of these entries contains the name of the | directory entries. Each of these entries contains the name of the | |||
directory entry, a cookie value for that entry, and the associated | directory entry, a cookie value for that entry, and the associated | |||
attributes as requested. The "eof" flag has a value of TRUE if there | attributes as requested. The "eof" flag has a value of TRUE if there | |||
are no more entries in the directory. | are no more entries in the directory. | |||
</t> | </t> | |||
<t> | <t> | |||
The cookie value is only meaningful to the server and is used | The cookie value is only meaningful to the server and is used | |||
as a cursor for the directory entry. As mentioned, this cookie | as a cursor for the directory entry. As mentioned, this cookie | |||
is used by the client for subsequent READDIR operations so that it may | is used by the client for subsequent READDIR operations so that it may | |||
continue reading a directory. The cookie is similar in concept to a | continue reading a directory. The cookie is similar in concept to a | |||
READ offset but MUST NOT be interpreted as such by the client. | READ offset but <bcp14>MUST NOT</bcp14> be interpreted as such by the clie | |||
Ideally, the cookie value SHOULD NOT change if the directory is | nt. | |||
Ideally, the cookie value <bcp14>SHOULD NOT</bcp14> change if the director | ||||
y is | ||||
modified since the client may be caching these values. | modified since the client may be caching these values. | |||
</t> | </t> | |||
<t> | <t> | |||
In some cases, the server may encounter an error while obtaining the | In some cases, the server may encounter an error while obtaining the | |||
attributes for a directory entry. Instead of returning an error for | attributes for a directory entry. Instead of returning an error for | |||
the entire READDIR operation, the server can instead return the | the entire READDIR operation, the server can instead return the | |||
attribute rdattr_error (<xref target="attrdef_rdattr_error"/>). With this , the server is able to | attribute rdattr_error (<xref target="attrdef_rdattr_error" format="defaul t"/>). With this, the server is able to | |||
communicate the failure to the client and not fail the entire | communicate the failure to the client and not fail the entire | |||
operation in the instance of what might be a transient failure. | operation in the instance of what might be a transient failure. | |||
Obviously, the client must request the fattr4_rdattr_error attribute | Obviously, the client must request the fattr4_rdattr_error attribute | |||
for this method to work properly. If the client does not request the | for this method to work properly. If the client does not request the | |||
attribute, the server has no choice but to return failure for the | attribute, the server has no choice but to return failure for the | |||
entire READDIR operation. | entire READDIR operation. | |||
</t> | </t> | |||
<t> | <t> | |||
For some file system environments, the directory entries "." and ".." | For some file system environments, the directory entries "." and ".." | |||
have special meaning, and in other environments, they do not. If the | have special meaning, and in other environments, they do not. If the | |||
server supports these special entries within a directory, they SHOULD | server supports these special entries within a directory, they <bcp14>SHOU | |||
NOT be returned to the client as part of the READDIR response. To | LD | |||
NOT</bcp14> be returned to the client as part of the READDIR response. To | ||||
enable some client environments, the cookie values of zero, 1, and 2 are | enable some client environments, the cookie values of zero, 1, and 2 are | |||
to be considered reserved. Note that the UNIX client will use these | to be considered reserved. Note that the UNIX client will use these | |||
values when combining the server's response and local representations | values when combining the server's response and local representations | |||
to enable a fully formed UNIX directory presentation to the | to enable a fully formed UNIX directory presentation to the | |||
application. | application. | |||
</t> | </t> | |||
<t> | <t> | |||
For READDIR arguments, cookie values of one and two SHOULD NOT be used, an | For READDIR arguments, cookie values of one and two <bcp14>SHOULD NOT</bcp | |||
d | 14> be used, and | |||
for READDIR results, cookie values of zero, one, and two SHOULD NOT be | for READDIR results, cookie values of zero, one, and two <bcp14>SHOULD NOT | |||
</bcp14> be | ||||
returned. | returned. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_READDIR_IMPLEMENTATION" title="IMPLEMENTATIO | <section toc="exclude" anchor="OP_READDIR_IMPLEMENTATION" numbered="true | |||
N"> | "> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
The server's file system directory representations | The server's file system directory representations | |||
can differ greatly. A client's programming | can differ greatly. A client's programming | |||
interfaces may also be bound to the local operating | interfaces may also be bound to the local operating | |||
environment in a way that does not translate well | environment in a way that does not translate well | |||
into the NFS protocol. Therefore, the use of the | into the NFS protocol. Therefore, the use of the | |||
dircount and maxcount fields are provided to enable | dircount and maxcount fields are provided to enable | |||
the client to provide hints to the server. If the | the client to provide hints to the server. If the | |||
client is aggressive about attribute collection | client is aggressive about attribute collection | |||
during a READDIR, the server has an idea of how to | during a READDIR, the server has an idea of how to | |||
limit the encoded response. | limit the encoded response. | |||
</t> | </t> | |||
<t> | <t> | |||
If dircount is zero, the server bounds the reply's | If dircount is zero, the server bounds the reply's | |||
size based on the request's maxcount field. | size based on the request's maxcount field. | |||
</t> | </t> | |||
<t> | <t> | |||
The cookieverf may be used by the server to help manage cookie values | The cookieverf may be used by the server to help manage cookie values | |||
that may become stale. It should be a rare occurrence that a server is | that may become stale. It should be a rare occurrence that a server is | |||
unable to continue properly reading a directory with the provided | unable to continue properly reading a directory with the provided | |||
cookie/cookieverf pair. The server SHOULD make every effort to avoid | cookie/cookieverf pair. The server <bcp14>SHOULD</bcp14> make every effor t to avoid | |||
this condition since the application at the client might be unable to | this condition since the application at the client might be unable to | |||
properly handle this type of failure. | properly handle this type of failure. | |||
</t> | </t> | |||
<t> | <t> | |||
The use of the cookieverf will also protect the client from using | The use of the cookieverf will also protect the client from using | |||
READDIR cookie values that might be stale. For example, if the file | READDIR cookie values that might be stale. For example, if the file | |||
system has been migrated, the server might or might not be able to use the | system has been migrated, the server might or might not be able to use the | |||
same cookie values to service READDIR as the previous server used. | same cookie values to service READDIR as the previous server used. | |||
With the client providing the cookieverf, the server is able to | With the client providing the cookieverf, the server is able to | |||
provide the appropriate response to the client. This prevents the | provide the appropriate response to the client. This prevents the | |||
case where the server accepts a cookie value but the underlying | case where the server accepts a cookie value but the underlying | |||
directory has changed and the response is invalid from the client's | directory has changed and the response is invalid from the client's | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_READLINK" numbered="true" toc="default"> | |||
$ --> | <name>Operation 27: READLINK - Read Symbolic Link</name> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <section toc="exclude" anchor="OP_READLINK_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_READLINK" title="Operation 27: READLINK - Read Symbolic Link | <sourcecode type="xdr"><![CDATA[ | |||
" > | ||||
<section toc="exclude" anchor="OP_READLINK_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
/* CURRENT_FH: symlink */ | /* CURRENT_FH: symlink */ | |||
void; | void;]]></sourcecode> | |||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_READLINK_RESULTS" numbered="true"> | |||
</section> | <name>RESULTS</name> | |||
<sourcecode type="xdr"><![CDATA[ | ||||
<section toc="exclude" anchor="OP_READLINK_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_READLINK_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_READLINK_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
READLINK reads the data associated with a symbolic | READLINK reads the data associated with a symbolic | |||
link. Depending on the value of the UTF-8 capability | link. Depending on the value of the UTF-8 capability | |||
attribute (<xref target="utf8_caps"/>), the data is encoded | attribute (<xref target="utf8_caps" format="default"/>), the data is encod ed | |||
in UTF-8. | in UTF-8. | |||
Whether created by an NFS client or created locally | Whether created by an NFS client or created locally | |||
on the server, the data in a symbolic link is not | on the server, the data in a symbolic link is not | |||
interpreted (except possibly to check for proper UTF-8 | interpreted (except possibly to check for proper UTF-8 | |||
encoding) when created, but is simply stored. | encoding) when created, but is simply stored. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_READLINK_IMPLEMENTATION" title="IMPLEMENTATI | <section toc="exclude" anchor="OP_READLINK_IMPLEMENTATION" numbered="tru | |||
ON"> | e"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
A symbolic link is nominally a pointer to another file. The data is | A symbolic link is nominally a pointer to another file. The data is | |||
not necessarily interpreted by the server, just stored in the file. | not necessarily interpreted by the server, just stored in the file. | |||
It is possible for a client implementation to store a pathname that | It is possible for a client implementation to store a pathname that | |||
is not meaningful to the server operating system in a symbolic link. | is not meaningful to the server operating system in a symbolic link. | |||
A READLINK operation returns the data to the client for | A READLINK operation returns the data to the client for | |||
interpretation. If different implementations want to share access to | interpretation. If different implementations want to share access to | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_REMOVE" numbered="true" toc="default"> | |||
$ --> | <name>Operation 28: REMOVE - Remove File System Object</name> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <section toc="exclude" anchor="OP_REMOVE_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_REMOVE" title="Operation 28: REMOVE - Remove File System Obj | <sourcecode type="xdr"><![CDATA[ | |||
ect" > | ||||
<section toc="exclude" anchor="OP_REMOVE_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct REMOVE4args { | struct REMOVE4args { | |||
/* CURRENT_FH: directory */ | /* CURRENT_FH: directory */ | |||
component4 target; | component4 target; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_REMOVE_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_REMOVE_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_REMOVE_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_REMOVE_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The REMOVE operation removes (deletes) a directory entry named by | The REMOVE operation removes (deletes) a directory entry named by | |||
filename from the directory corresponding to the current filehandle. | filename from the directory corresponding to the current filehandle. | |||
If the entry in the directory was the last reference to the | If the entry in the directory was the last reference to the | |||
corresponding file system object, the object may be destroyed. | corresponding file system object, the object may be destroyed. | |||
The directory may be either of type NF4DIR or NF4ATTRDIR. | The directory may be either of type NF4DIR or NF4ATTRDIR. | |||
</t> | </t> | |||
<t> | <t> | |||
For the directory where the filename was removed, the server | For the directory where the filename was removed, the server | |||
returns change_info4 information in cinfo. With the atomic field of | returns change_info4 information in cinfo. With the atomic field of | |||
the change_info4 data type, the server will indicate if the before and | the change_info4 data type, the server will indicate if the before and | |||
after change attributes were obtained atomically with respect to the | after change attributes were obtained atomically with respect to the | |||
removal. | removal. | |||
</t> | </t> | |||
<t> | <t> | |||
If the target has a length of zero, or if | If the target has a length of zero, or if | |||
the target does not obey the UTF-8 definition (and | the target does not obey the UTF-8 definition (and | |||
the server is enforcing UTF-8 encoding; see <xref | the server is enforcing UTF-8 encoding; see <xref target="utf8_caps" forma | |||
target="utf8_caps"/>), the error NFS4ERR_INVAL will | t="default"/>), the error NFS4ERR_INVAL will | |||
be returned. | be returned. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_REMOVE_IMPLEMENTATION" title="IMPLEMENTATION | <section toc="exclude" anchor="OP_REMOVE_IMPLEMENTATION" numbered="true" | |||
"> | > | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
NFSv3 required a different operator RMDIR for directory | NFSv3 required a different operator RMDIR for directory | |||
removal and REMOVE for non-directory removal. This allowed clients to | removal and REMOVE for non-directory removal. This allowed clients to | |||
skip checking the file type when being passed a non-directory delete | skip checking the file type when being passed a non-directory delete | |||
system call (e.g., <xref target="unlink">unlink()</xref> in POSIX) to remo ve a directory, as well as | system call (e.g., <xref target="unlink" format="default">unlink()</xref> in POSIX) to remove a directory, as well as | |||
the converse (e.g., a rmdir() on a non-directory) because they knew the | the converse (e.g., a rmdir() on a non-directory) because they knew the | |||
server would check the file type. NFSv4.1 REMOVE can be used to | server would check the file type. NFSv4.1 REMOVE can be used to | |||
delete any directory entry independent of its file type. The | delete any directory entry independent of its file type. The | |||
implementor of an NFSv4.1 client's entry points from the | implementor of an NFSv4.1 client's entry points from the | |||
unlink() and rmdir() system calls should first check the file type | unlink() and rmdir() system calls should first check the file type | |||
against the types the system call is allowed to remove before sending | against the types the system call is allowed to remove before sending | |||
a REMOVE operation. Alternatively, the implementor can produce a COMPOUND call | a REMOVE operation. Alternatively, the implementor can produce a COMPOUND call | |||
that includes a LOOKUP/VERIFY sequence of operations to verify the file ty pe before | that includes a LOOKUP/VERIFY sequence of operations to verify the file ty pe before | |||
a REMOVE operation in the same COMPOUND call. | a REMOVE operation in the same COMPOUND call. | |||
</t> | </t> | |||
<t> | <t> | |||
The concept of last reference is server | The concept of last reference is server | |||
specific. However, if the numlinks field in the | specific. However, if the numlinks field in the | |||
previous attributes of the object had the value 1, | previous attributes of the object had the value 1, | |||
the client should not rely on referring to the | the client should not rely on referring to the | |||
object via a filehandle. Likewise, the client | object via a filehandle. Likewise, the client | |||
should not rely on the resources (disk space, | should not rely on the resources (disk space, | |||
directory entry, and so on) formerly associated | directory entry, and so on) formerly associated | |||
with the object becoming immediately available. | with the object becoming immediately available. | |||
Thus, if a client needs to be able to continue to | Thus, if a client needs to be able to continue to | |||
access a file after using REMOVE to remove it, the | access a file after using REMOVE to remove it, the | |||
client should take steps to make sure that the file | client should take steps to make sure that the file | |||
will still be accessible. While the traditional | will still be accessible. While the traditional | |||
mechanism used is to RENAME the file from its old | mechanism used is to RENAME the file from its old | |||
name to a new hidden name, the NFSv4.1 OPEN operation | name to a new hidden name, the NFSv4.1 OPEN operation | |||
MAY return a result flag, OPEN4_RESULT_PRESERVE_UNLINKED, | <bcp14>MAY</bcp14> return a result flag, OPEN4_RESULT_PRESERVE_UNLINKED, | |||
which indicates to the client that the file will be | which indicates to the client that the file will be | |||
preserved if the file has an outstanding open (see <xref | preserved if the file has an outstanding open (see <xref target="OP_OPEN" | |||
target="OP_OPEN"/>). | format="default"/>). | |||
</t> | </t> | |||
<t> | <t> | |||
If the server finds that the file is still open when the REMOVE | If the server finds that the file is still open when the REMOVE | |||
arrives: | arrives: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
The server SHOULD NOT delete the file's directory entry if the | <li> | |||
The server <bcp14>SHOULD NOT</bcp14> delete the file's directory entry | ||||
if the | ||||
file was opened with OPEN4_SHARE_DENY_WRITE or | file was opened with OPEN4_SHARE_DENY_WRITE or | |||
OPEN4_SHARE_DENY_BOTH. | OPEN4_SHARE_DENY_BOTH. | |||
</t> | </li> | |||
<t> | <li> | |||
If the file was not opened with OPEN4_SHARE_DENY_WRITE or | If the file was not opened with OPEN4_SHARE_DENY_WRITE or | |||
OPEN4_SHARE_DENY_BOTH, the server SHOULD delete the file's | OPEN4_SHARE_DENY_BOTH, the server <bcp14>SHOULD</bcp14> delete the fil e's | |||
directory entry. However, until last CLOSE of the file, | directory entry. However, until last CLOSE of the file, | |||
the server MAY continue to allow access to the file via | the server <bcp14>MAY</bcp14> continue to allow access to the file via | |||
its filehandle. | its filehandle. | |||
</t> | </li> | |||
<t> | <li> | |||
The server MUST NOT delete the directory | The server <bcp14>MUST NOT</bcp14> delete the directory | |||
entry if the reply from OPEN had the flag | entry if the reply from OPEN had the flag | |||
OPEN4_RESULT_PRESERVE_UNLINKED set. | OPEN4_RESULT_PRESERVE_UNLINKED set. | |||
</t> | </li> | |||
</ul> | ||||
</list> | <t> | |||
</t> | The server <bcp14>MAY</bcp14> implement its own restrictions on removal | |||
<t> | ||||
The server MAY implement its own restrictions on removal | ||||
of a file while it is open. The server might disallow | of a file while it is open. The server might disallow | |||
such a REMOVE (or a removal that occurs | such a REMOVE (or a removal that occurs | |||
as part of RENAME). The conditions that influence the restrictions | as part of RENAME). The conditions that influence the restrictions | |||
on removal of a file while it is still open include: | on removal of a file while it is still open include: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Whether certain access protocols (i.e., not just | Whether certain access protocols (i.e., not just | |||
NFS) are holding the file open. | NFS) are holding the file open. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
Whether particular options, access modes, or policies on the | Whether particular options, access modes, or policies on the | |||
server are enabled. | server are enabled. | |||
</t> | </li> | |||
</ul> | ||||
</list> | <t> | |||
</t> | ||||
<t> | ||||
If a file has an outstanding OPEN and this prevents the | If a file has an outstanding OPEN and this prevents the | |||
removal of the file's directory entry, | removal of the file's directory entry, | |||
the error NFS4ERR_FILE_OPEN is returned. | the error NFS4ERR_FILE_OPEN is returned. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
Where the determination above cannot be made | Where the determination above cannot be made | |||
definitively because delegations are being held, | definitively because delegations are being held, | |||
they MUST be recalled to allow processing of the | they <bcp14>MUST</bcp14> be recalled to allow processing of the | |||
REMOVE to continue. When a delegation is held, | REMOVE to continue. When a delegation is held, | |||
the server has no reliable knowledge of the status of OPENs for | the server has no reliable knowledge of the status of OPENs for | |||
that client, so unless | that client, so unless | |||
there are files opened with the particular deny modes | there are files opened with the particular deny modes | |||
by clients without delegations, the determination | by clients without delegations, the determination | |||
cannot be made until delegations are recalled, and | cannot be made until delegations are recalled, and | |||
the operation cannot proceed until each sufficient | the operation cannot proceed until each sufficient | |||
delegation has been returned or revoked to allow | delegation has been returned or revoked to allow | |||
the server to make a correct determination. | the server to make a correct determination. | |||
</t> | </t> | |||
<t> | <t> | |||
In all cases in which delegations are recalled, the server | In all cases in which delegations are recalled, the server | |||
is likely to return one or more NFS4ERR_DELAY errors while | is likely to return one or more NFS4ERR_DELAY errors while | |||
delegations remain outstanding. | delegations remain outstanding. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
If the current filehandle designates a directory for | If the current filehandle designates a directory for | |||
which another client holds a directory delegation, | which another client holds a directory delegation, | |||
then, unless the situation can be resolved by sending | then, unless the situation can be resolved by sending | |||
a notification, the directory delegation MUST be | a notification, the directory delegation <bcp14>MUST</bcp14> be | |||
recalled, and the operation MUST NOT proceed until | recalled, and the operation <bcp14>MUST NOT</bcp14> proceed until | |||
the delegation is returned or revoked. Except where | the delegation is returned or revoked. Except where | |||
this happens very quickly, one or more NFS4ERR_DELAY | this happens very quickly, one or more NFS4ERR_DELAY | |||
errors will be returned to requests made while | errors will be returned to requests made while | |||
delegation remains outstanding. | delegation remains outstanding. | |||
</t> | </t> | |||
<t> | <t> | |||
When the current filehandle designates a directory | When the current filehandle designates a directory | |||
for which one or more directory delegations | for which one or more directory delegations | |||
exist, then, when those delegations request | exist, then, when those delegations request | |||
such notifications, NOTIFY4_REMOVE_ENTRY will be | such notifications, NOTIFY4_REMOVE_ENTRY will be | |||
generated as a result of this operation. | generated as a result of this operation. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
Note that when a remove occurs as a result of a | Note that when a remove occurs as a result of a | |||
RENAME, NOTIFY4_REMOVE_ENTRY will only be generated | RENAME, NOTIFY4_REMOVE_ENTRY will only be generated | |||
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"/>. | notification in <xref target="OP_CB_NOTIFY" format="default"/>. | |||
</t> | ||||
</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="OP_RENAME" title="Operation 29: RENAME - Rename Directory Entry | ||||
" > | ||||
<section toc="exclude" anchor="OP_RENAME_ARGUMENTS" title="ARGUMENTS"> | </t> | |||
<figure> | </section> | |||
<artwork> | </section> | |||
<section anchor="OP_RENAME" numbered="true" toc="default"> | ||||
<name>Operation 29: RENAME - Rename Directory Entry</name> | ||||
<section toc="exclude" anchor="OP_RENAME_ARGUMENTS" numbered="true"> | ||||
<name>ARGUMENTS</name> | ||||
<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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_RENAME_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_RENAME_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_RENAME_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_RENAME_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The RENAME operation renames the object identified by oldname in the | The RENAME operation renames the object identified by oldname in the | |||
source directory corresponding to the saved filehandle, as set by the | source directory corresponding to the saved filehandle, as set by the | |||
SAVEFH operation, to newname in the target directory corresponding to | SAVEFH operation, to newname in the target directory corresponding to | |||
the current filehandle. The operation is required to be atomic to the | the current filehandle. The operation is required to be atomic to the | |||
client. Source and target directories MUST reside on the same | client. Source and target directories <bcp14>MUST</bcp14> reside on the s ame | |||
file system on the server. On success, the current filehandle will | file system on the server. On success, the current filehandle will | |||
continue to be the target directory. | continue to be the target directory. | |||
</t> | </t> | |||
<t> | <t> | |||
If the target directory already contains an entry with the name | If the target directory already contains an entry with the name | |||
newname, the source object MUST be compatible with the target: either | newname, the source object <bcp14>MUST</bcp14> be compatible with the targ | |||
both are non-directories or both are directories and the target MUST | et: either | |||
both are non-directories or both are directories and the target <bcp14>MUS | ||||
T</bcp14> | ||||
be empty. | be empty. | |||
If compatible, the existing target is removed before the | If compatible, the existing target is removed before the | |||
rename occurs or, preferably, the target is removed atomically as | rename occurs or, preferably, the target is removed atomically as | |||
part of the rename. | part of the rename. | |||
See <xref target="OP_REMOVE_IMPLEMENTATION" /> | See <xref target="OP_REMOVE_IMPLEMENTATION" format="default"/> | |||
for client and server actions whenever a target is removed. | for client and server actions whenever a target is removed. | |||
Note however that when the removal is performed atomically with the | Note however that when the removal is performed atomically with the | |||
rename, certain parts of the removal described there are integrated | rename, certain parts of the removal described there are integrated | |||
with the rename. For example, notification of the removal will not | with the rename. For example, notification of the removal will not | |||
be via a NOTIFY4_REMOVE_ENTRY but will be indicated as part of the | be via a NOTIFY4_REMOVE_ENTRY but will be indicated as part of the | |||
NOTIFY4_ADD_ENTRY or NOTIFY4_RENAME_ENTRY generated by the rename. | NOTIFY4_ADD_ENTRY or NOTIFY4_RENAME_ENTRY generated by the rename. | |||
</t> | </t> | |||
<t> | <t> | |||
If the source object and the target are not | If the source object and the target are not | |||
compatible or if the target is a directory but not empty, the server | compatible or if the target is a directory but not empty, the server | |||
will return the error NFS4ERR_EXIST. | will return the error NFS4ERR_EXIST. | |||
</t> | </t> | |||
<t> | <t> | |||
If oldname and newname both refer to the same | If oldname and newname both refer to the same | |||
file (e.g., they might be hard links of each | file (e.g., they might be hard links of each | |||
other), then unless the file is open (see <xref | other), then unless the file is open (see <xref target="OP_RENAME_IMPLEMEN | |||
target="OP_RENAME_IMPLEMENTATION"/>), RENAME MUST | TATION" format="default"/>), RENAME <bcp14>MUST</bcp14> | |||
perform no action and return NFS4_OK. | perform no action and return NFS4_OK. | |||
</t> | </t> | |||
<t> | <t> | |||
For both directories involved in the RENAME, the server returns | For both directories involved in the RENAME, the server returns | |||
change_info4 information. With the atomic field of the change_info4 | change_info4 information. With the atomic field of the change_info4 | |||
data type, the server will indicate if the before and after change | data type, the server will indicate if the before and after change | |||
attributes were obtained atomically with respect to the rename. | attributes were obtained atomically with respect to the rename. | |||
</t> | </t> | |||
<t> | <t> | |||
If oldname refers to a named attribute and the saved and current | If oldname refers to a named attribute and the saved and current | |||
filehandles refer to different file system objects, the server will | filehandles refer to different file system objects, the server will | |||
return NFS4ERR_XDEV just as if the saved and current filehandles | return NFS4ERR_XDEV just as if the saved and current filehandles | |||
represented directories on different file systems. | represented directories on different file systems. | |||
</t> | </t> | |||
<t> | <t> | |||
If oldname or newname has a length of zero, or if oldname or | If oldname or newname has a length of zero, or if oldname or | |||
newname does not obey the UTF-8 definition, the error NFS4ERR_INVAL | newname does not obey the UTF-8 definition, the error NFS4ERR_INVAL | |||
will be returned. | will be returned. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_RENAME_IMPLEMENTATION" numbered="true" | ||||
<section toc="exclude" anchor="OP_RENAME_IMPLEMENTATION" title="IMPLEMENTATION | > | |||
"> | <name>IMPLEMENTATION</name> | |||
<t> | <t> | |||
The server MAY impose restrictions on the RENAME | The server <bcp14>MAY</bcp14> impose restrictions on the RENAME | |||
operation such that RENAME may not be done when the | operation such that RENAME may not be done when the | |||
file being renamed is open or when that open is done | file being renamed is open or when that open is done | |||
by particular protocols, or with particular options | by particular protocols, or with particular options | |||
or access modes. Similar restrictions may be applied | or access modes. Similar restrictions may be applied | |||
when a file exists with the target name and is open. | when a file exists with the target name and is open. | |||
When RENAME is rejected because of such restrictions, | When RENAME is rejected because of such restrictions, | |||
the error NFS4ERR_FILE_OPEN is returned. | the error NFS4ERR_FILE_OPEN is returned. | |||
</t> | </t> | |||
<t> | <t> | |||
When oldname and rename refer to the same file and | When oldname and rename refer to the same file and | |||
that file is open in a fashion such that RENAME | that file is open in a fashion such that RENAME | |||
would normally be rejected with NFS4ERR_FILE_OPEN | would normally be rejected with NFS4ERR_FILE_OPEN | |||
if oldname and newname were different files, then | if oldname and newname were different files, then | |||
RENAME SHOULD be rejected with NFS4ERR_FILE_OPEN. | RENAME <bcp14>SHOULD</bcp14> be rejected with NFS4ERR_FILE_OPEN. | |||
</t> | </t> | |||
<t> | <t> | |||
If a server does implement such restrictions and those restrictions | If a server does implement such restrictions and those restrictions | |||
include cases of NFSv4 opens preventing successful execution of | include cases of NFSv4 opens preventing successful execution of | |||
a rename, the server needs to recall any delegations that could | a rename, the server needs to recall any delegations that could | |||
hide the existence of opens relevant to that decision. This is | hide the existence of opens relevant to that decision. This is | |||
because when a client holds a delegation, the server | because when a client holds a delegation, the server | |||
might not have an accurate account of the opens for that client, since | might not have an accurate account of the opens for that client, since | |||
the client may execute OPENs and CLOSEs locally. The RENAME operation | the client may execute OPENs and CLOSEs locally. The RENAME operation | |||
need only be delayed until a definitive result can be obtained. For | need only be delayed until a definitive result can be obtained. For | |||
example, if there are multiple delegations and one of them establishes | example, if there are multiple delegations and one of them establishes | |||
an open whose presence would prevent the rename, given the server's | an open whose presence would prevent the rename, given the server's | |||
semantics, NFS4ERR_FILE_OPEN may be returned to the caller as soon | semantics, NFS4ERR_FILE_OPEN may be returned to the caller as soon | |||
as that delegation is returned without waiting for other delegations | as that delegation is returned without waiting for other delegations | |||
to be returned. Similarly, if such opens are not associated with | to be returned. Similarly, if such opens are not associated with | |||
delegations, NFS4ERR_FILE_OPEN can be returned immediately with no | delegations, NFS4ERR_FILE_OPEN can be returned immediately with no | |||
delegation recall being done. | delegation recall being done. | |||
</t> | </t> | |||
<t> | <t> | |||
If the current filehandle or the saved filehandle designates a | If the current filehandle or the saved filehandle designates a | |||
directory for which another client holds a directory delegation, | directory for which another client holds a directory delegation, | |||
then, unless the situation can be resolved by sending a notification, | then, unless the situation can be resolved by sending a notification, | |||
the delegation MUST be recalled, and the operation cannot proceed | the delegation <bcp14>MUST</bcp14> be recalled, and the operation cannot p roceed | |||
until the delegation is returned or revoked. Except where this | until the delegation is returned or revoked. 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 delegation remains outstanding. | returned to requests made while delegation remains outstanding. | |||
</t> | </t> | |||
<t> | <t> | |||
When the current and saved filehandles are the | When the current and saved filehandles are the | |||
same and they designate a directory for which one | same and they designate a directory for which one | |||
or more directory delegations exist, then, when | or more directory delegations exist, then, when | |||
those delegations request such notifications, | those delegations request such notifications, | |||
a notification of type NOTIFY4_RENAME_ENTRY | a notification of type NOTIFY4_RENAME_ENTRY | |||
will be generated as a result of this operation. | will be generated as a result of this operation. | |||
When oldname and rename refer to the same file, | When oldname and rename refer to the same file, | |||
no notification is generated (because, as <xref | no notification is generated (because, as <xref target="OP_RENAME_DESCRIPT | |||
target="OP_RENAME_DESCRIPTION"/> states, the server | ION" format="default"/> states, the server | |||
MUST take no action). When a file is removed | <bcp14>MUST</bcp14> take no action). When a file is removed | |||
because it has the same name as the target, if | because it has the same name as the target, if | |||
that removal is done atomically with the rename, | that removal is done atomically with the rename, | |||
a NOTIFY4_REMOVE_ENTRY notification will not be | a NOTIFY4_REMOVE_ENTRY notification will not be | |||
generated. Instead, the deletion of the file will | generated. Instead, the deletion of the file will | |||
be reported as part of the NOTIFY4_RENAME_ENTRY | be reported as part of the NOTIFY4_RENAME_ENTRY | |||
notification. | notification. | |||
</t> | </t> | |||
<t> | <t> | |||
When the current and saved filehandles are not the same: | When the current and saved filehandles are not the same: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If the current filehandle designates a directory for which | If the current filehandle designates a directory for which | |||
one or more directory delegations exist, then, when those | one or more directory delegations exist, then, when those | |||
delegations request such notifications, NOTIFY4_ADD_ENTRY | delegations request such notifications, NOTIFY4_ADD_ENTRY | |||
will be generated as a result of this operation. When a file | will be generated as a result of this operation. When a file | |||
is removed because it has the same name as the target, if that | is removed because it has the same name as the target, if that | |||
removal is done atomically with the rename, a | removal is done atomically with the rename, a | |||
NOTIFY4_REMOVE_ENTRY notification will not be generated. | NOTIFY4_REMOVE_ENTRY notification will not be generated. | |||
Instead, the deletion of the file will be reported as part | Instead, the deletion of the file will be reported as part | |||
of the NOTIFY4_ADD_ENTRY notification. | of the NOTIFY4_ADD_ENTRY notification. | |||
</t> | </li> | |||
<t> | <li> | |||
If the saved filehandle designates a directory for which | If the saved filehandle designates a directory for which | |||
one or more directory delegations exist, then, when those | one or more directory delegations exist, then, when those | |||
delegations request such notifications, NOTIFY4_REMOVE_ENTRY | delegations request such notifications, NOTIFY4_REMOVE_ENTRY | |||
will be generated as a result of this operation. | will be generated as a result of this operation. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
</t> | ||||
<t> | ||||
If the object being renamed has file delegations | If the object being renamed has file delegations | |||
held by clients other than the one doing the RENAME, | held by clients other than the one doing the RENAME, | |||
the delegations MUST be recalled, and the | the delegations <bcp14>MUST</bcp14> be recalled, and the | |||
operation cannot proceed | operation cannot proceed | |||
until each such delegation is returned | until each such delegation is returned | |||
or revoked. Note that in the case of multiply linked files, | or revoked. Note that in the case of multiply linked files, | |||
the delegation recall requirement applies even if the | the delegation recall requirement applies even if the | |||
delegation was obtained through a different name than the | delegation was obtained through a different name than the | |||
one being renamed. | one being renamed. | |||
In all cases in which delegations are recalled, the server | In all cases in which delegations are recalled, the server | |||
is likely to return one or more NFS4ERR_DELAY errors while the | is likely to return one or more NFS4ERR_DELAY errors while the | |||
delegation(s) remains outstanding, although it might not do that if the | delegation(s) remains outstanding, although it might not do that if the | |||
delegations are returned quickly. | delegations are returned quickly. | |||
</t> | </t> | |||
<t> | <t> | |||
The RENAME operation must be atomic to the client. The statement | The RENAME operation must be atomic to the client. The statement | |||
"source and target directories MUST reside on the same file system | "source and target directories <bcp14>MUST</bcp14> reside on the same file system | |||
on the server" | on the server" | |||
means that the fsid fields in the attributes for the | means that the fsid fields in the attributes for the | |||
directories are the same. If they reside on different file systems, | directories are the same. If they reside on different file systems, | |||
the error NFS4ERR_XDEV is returned. | the error NFS4ERR_XDEV is returned. | |||
</t> | </t> | |||
<t> | <t> | |||
Based on the value of the fh_expire_type attribute for the object, the | Based on the value of the fh_expire_type attribute for the object, the | |||
filehandle may or may not expire on a RENAME. However, server | filehandle may or may not expire on a RENAME. However, server | |||
implementors are strongly encouraged to attempt to keep filehandles | implementors are strongly encouraged to attempt to keep filehandles | |||
from expiring in this fashion. | from expiring in this fashion. | |||
</t> | </t> | |||
<t> | <t> | |||
On some servers, the file names "." and ".." are illegal as either | On some servers, the file names "." and ".." are illegal as either | |||
oldname or newname, and will result in the error NFS4ERR_BADNAME. | oldname or newname, and will result in the error NFS4ERR_BADNAME. | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_RESTOREFH" numbered="true" toc="default"> | |||
$ --> | <name>Operation 31: RESTOREFH - Restore Saved Filehandle</name> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <section toc="exclude" anchor="OP_RESTOREFH_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_RESTOREFH" title="Operation 31: RESTOREFH - Restore Saved Fi | <sourcecode type="xdr"><![CDATA[ | |||
lehandle" > | ||||
<section toc="exclude" anchor="OP_RESTOREFH_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
/* SAVED_FH: */ | /* SAVED_FH: */ | |||
void; | void;]]></sourcecode> | |||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_RESTOREFH_RESULTS" numbered="true"> | |||
</section> | <name>RESULTS</name> | |||
<sourcecode type="xdr"><![CDATA[ | ||||
<section toc="exclude" anchor="OP_RESTOREFH_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_RESTOREFH_DESCRIPTION" numbered="true" | |||
</figure> | > | |||
</section> | <name>DESCRIPTION</name> | |||
<t> | ||||
<section toc="exclude" anchor="OP_RESTOREFH_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The RESTOREFH operation sets the current filehandle and stateid to the val ues in the | The RESTOREFH operation sets the current filehandle and stateid to the val ues in the | |||
saved filehandle and stateid. If | saved filehandle and stateid. If | |||
there is no saved filehandle, then the server will | there is no saved filehandle, then the server will | |||
return the error NFS4ERR_NOFILEHANDLE. | return the error NFS4ERR_NOFILEHANDLE. | |||
</t> | </t> | |||
<t> | <t> | |||
See <xref target="current_filehandle"/> for more details on the | See <xref target="current_filehandle" format="default"/> for more details | |||
on the | ||||
current filehandle. | current filehandle. | |||
</t> | </t> | |||
<t> | <t> | |||
See <xref target="current_stateid"/> 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_RESTOREFH_IMPLEMENTATION" title="IMPLEMENTAT | <section toc="exclude" anchor="OP_RESTOREFH_IMPLEMENTATION" numbered="tr | |||
ION"> | ue"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<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., | |||
<figure> | </t> | |||
<artwork> | <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) | GETATTR attrbits (post-op dir attrs)]]></sourcecode> | |||
</artwork> | </section> | |||
</figure> | </section> | |||
</t> | <section anchor="OP_SAVEFH" numbered="true" toc="default"> | |||
</section> | <name>Operation 32: SAVEFH - Save Current Filehandle</name> | |||
</section> | <section toc="exclude" anchor="OP_SAVEFH_ARGUMENTS" numbered="true"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>ARGUMENTS</name> | |||
$ --> | <sourcecode type="xdr"><![CDATA[ | |||
<!-- Copyright (C) The IETF Trust (2007) --> | ||||
<!-- Copyright (C) The Internet Society (2006) --> | ||||
<section anchor="OP_SAVEFH" title="Operation 32: SAVEFH - Save Current Filehandl | ||||
e" > | ||||
<section toc="exclude" anchor="OP_SAVEFH_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
/* CURRENT_FH: */ | /* CURRENT_FH: */ | |||
void; | void;]]></sourcecode> | |||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_SAVEFH_RESULTS" numbered="true"> | |||
</section> | <name>RESULTS</name> | |||
<sourcecode type="xdr"><![CDATA[ | ||||
<section toc="exclude" anchor="OP_SAVEFH_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_SAVEFH_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_SAVEFH_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The SAVEFH operation saves the current filehandle and stateid. | The SAVEFH operation saves the current filehandle and stateid. | |||
If a previous filehandle was saved, then | If a previous filehandle was saved, then | |||
it is no longer accessible. The saved filehandle can be restored as | it is no longer accessible. The saved filehandle can be restored as | |||
the current filehandle with the RESTOREFH operator. | the current filehandle with the RESTOREFH operator. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
<t> | <t> | |||
See <xref target="current_filehandle"/> for more details on the | See <xref target="current_filehandle" format="default"/> for more details | |||
on the | ||||
current filehandle. | current filehandle. | |||
</t> | </t> | |||
<t> | <t> | |||
See <xref target="current_stateid"/> 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" title="IMPLEMENTATION | <section toc="exclude" anchor="OP_SAVEFH_IMPLEMENTATION" numbered="true" | |||
"> | > | |||
<t> | <name>IMPLEMENTATION</name> | |||
</t> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="OP_SECINFO" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 33: SECINFO - Obtain Available Security</name> | |||
$ --> | <section toc="exclude" anchor="OP_SECINFO_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <name>ARGUMENTS</name> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <sourcecode type="xdr"><![CDATA[ | |||
<section anchor="OP_SECINFO" title="Operation 33: SECINFO - Obtain Available Sec | ||||
urity" > | ||||
<section toc="exclude" anchor="OP_SECINFO_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct SECINFO4args { | struct SECINFO4args { | |||
/* CURRENT_FH: directory */ | /* CURRENT_FH: directory */ | |||
component4 name; | component4 name; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_SECINFO_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_SECINFO_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
/* | /* | |||
* 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 34104 ¶ | skipping to change at line 34262 ¶ | |||
}; | }; | |||
/* RPCSEC_GSS has a value of '6' - See RFC 2203 */ | /* RPCSEC_GSS has a value of '6' - See RFC 2203 */ | |||
union secinfo4 switch (uint32_t flavor) { | union secinfo4 switch (uint32_t flavor) { | |||
case RPCSEC_GSS: | case RPCSEC_GSS: | |||
rpcsec_gss_info flavor_info; | rpcsec_gss_info flavor_info; | |||
default: | default: | |||
void; | void; | |||
}; | }; | |||
typedef secinfo4 SECINFO4resok<>; | typedef secinfo4 SECINFO4resok<>; | |||
union SECINFO4res switch (nfsstat4 status) { | union SECINFO4res switch (nfsstat4 status) { | |||
case NFS4_OK: | case NFS4_OK: | |||
/* CURRENTFH: consumed */ | /* CURRENTFH: consumed */ | |||
SECINFO4resok resok4; | SECINFO4resok resok4; | |||
default: | default: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_SECINFO_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_SECINFO_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The SECINFO operation is used by the client to obtain a list of | The SECINFO operation is used by the client to obtain a list of | |||
valid RPC authentication flavors for a specific directory | valid RPC authentication flavors for a specific directory | |||
filehandle, file name pair. SECINFO should apply the same | filehandle, file name pair. SECINFO should apply the same | |||
access methodology used for LOOKUP when evaluating the name. | access methodology used for LOOKUP when evaluating the name. | |||
Therefore, if the requester does not have the appropriate access | Therefore, if the requester does not have the appropriate access | |||
to LOOKUP the name, then SECINFO MUST behave the same way and | to LOOKUP the name, then SECINFO <bcp14>MUST</bcp14> behave the same way a nd | |||
return NFS4ERR_ACCESS. | return NFS4ERR_ACCESS. | |||
</t> | </t> | |||
<t> | <t> | |||
The result will contain an array that represents the security | The result will contain an array that represents the security | |||
mechanisms available, with an order corresponding to the | mechanisms available, with an order corresponding to the | |||
server's preferences, the most preferred being first in the | server's preferences, the most preferred being first in the | |||
array. The client is free to pick whatever security mechanism it | array. The client is free to pick whatever security mechanism it | |||
both desires and supports, or to pick in the server's preference | both desires and supports, or to pick in the server's preference | |||
order the first one it supports. The array entries are | order the first one it supports. The array entries are | |||
represented by the secinfo4 structure. The field 'flavor' will | represented by the secinfo4 structure. The field 'flavor' will | |||
contain a value of AUTH_NONE, AUTH_SYS (as defined in <xref | contain a value of AUTH_NONE, AUTH_SYS (as defined in <xref target="RFC553 | |||
target="RFC5531">RFC 5531</xref>), or RPCSEC_GSS (as defined in | 1" format="default">RFC 5531</xref>), or RPCSEC_GSS (as defined in | |||
<xref target="RFC2203">RFC 2203</xref>). The field flavor can | <xref target="RFC2203" format="default">RFC 2203</xref>). The field flavor | |||
can | ||||
also be any other security flavor registered with IANA. | also be any other security flavor registered with IANA. | |||
</t> | </t> | |||
<t> | <t> | |||
For the flavors AUTH_NONE and AUTH_SYS, no additional security | For the flavors AUTH_NONE and AUTH_SYS, no additional security | |||
information is returned. The same is true of many (if not most) | information is returned. The same is true of many (if not most) | |||
other security flavors, including AUTH_DH. For a return value of | other security flavors, including AUTH_DH. For a return value of | |||
RPCSEC_GSS, a security triple is returned that contains the | RPCSEC_GSS, a security triple is returned that contains the | |||
mechanism object identifier (OID, as defined in <xref | mechanism object identifier (OID, as defined in <xref target="RFC2743" for | |||
target="RFC2743">RFC 2743</xref>), the quality of protection (as | mat="default">RFC 2743</xref>), the quality of protection (as | |||
defined in <xref target="RFC2743">RFC 2743</xref>), and the | defined in <xref target="RFC2743" format="default">RFC 2743</xref>), and t | |||
service type (as defined in <xref | he | |||
target="RFC2203">RFC 2203</xref>). It is possible for SECINFO to | service type (as defined in <xref target="RFC2203" format="default">RFC 22 | |||
03</xref>). It is possible for SECINFO to | ||||
return multiple entries with flavor equal to RPCSEC_GSS with | return multiple entries with flavor equal to RPCSEC_GSS with | |||
different security triple values. | different security triple values. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle is consumed (see | On success, the current filehandle is consumed (see | |||
<xref target="aftersecinfo" />), and if the | <xref target="aftersecinfo" format="default"/>), and if the | |||
next operation after SECINFO tries to use the current filehandle, | next operation after SECINFO tries to use the current filehandle, | |||
that operation will fail with the status NFS4ERR_NOFILEHANDLE. | that operation will fail with the status NFS4ERR_NOFILEHANDLE. | |||
</t> | </t> | |||
<t> | <t> | |||
If the name has a length of zero, or if the name does not obey | If the name has a length of zero, or if the name does not obey | |||
the UTF-8 definition (assuming UTF-8 capabilities are enabled; see | the UTF-8 definition (assuming UTF-8 capabilities are enabled; see | |||
<xref target="utf8_caps"/>), the error NFS4ERR_INVAL will be returned. | <xref target="utf8_caps" format="default"/>), the error NFS4ERR_INVAL will | |||
</t> | be returned. | |||
<t> | </t> | |||
See <xref target="Security_Service_Negotiation"/> | <t> | |||
See <xref target="Security_Service_Negotiation" format="default"/> | ||||
for additional information on the use of SECINFO. | for additional information on the use of SECINFO. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_SECINFO_IMPLEMENTATION" title="IMPLEMENTATIO | <section toc="exclude" anchor="OP_SECINFO_IMPLEMENTATION" numbered="true | |||
N"> | "> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
The SECINFO operation is expected to be used by the NFS client | The SECINFO operation is expected to be used by the NFS client | |||
when the error value of NFS4ERR_WRONGSEC is returned from | when the error value of NFS4ERR_WRONGSEC is returned from | |||
another NFS operation. This signifies to the client that the | another NFS operation. This signifies to the client that the | |||
server's security policy is different from what the client is | server's security policy is different from what the client is | |||
currently using. At this point, the client is expected to | currently using. At this point, the client is expected to | |||
obtain a list of possible security flavors and choose what best | obtain a list of possible security flavors and choose what best | |||
suits its policies. | suits its policies. | |||
</t> | </t> | |||
<t> | <t> | |||
As mentioned, the server's security | As mentioned, the server's security | |||
policies will determine when a client | policies will determine when a client | |||
request receives NFS4ERR_WRONGSEC. See <xref | request receives NFS4ERR_WRONGSEC. See <xref target="error_op_returns | |||
target="error_op_returns"/> for a list of operations | " format="default"/> for a list of operations | |||
that can return NFS4ERR_WRONGSEC. In addition, | that can return NFS4ERR_WRONGSEC. In addition, | |||
when READDIR returns attributes, the rdattr_error | when READDIR returns attributes, the rdattr_error | |||
(<xref target="attrdef_rdattr_error" />) | (<xref target="attrdef_rdattr_error" format="default"/>) | |||
can contain NFS4ERR_WRONGSEC. Note that CREATE and | can contain NFS4ERR_WRONGSEC. Note that CREATE and | |||
REMOVE MUST NOT return NFS4ERR_WRONGSEC. The | REMOVE <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC. The | |||
rationale for CREATE is that unless the | rationale for CREATE is that unless the | |||
target name exists, it cannot have a separate | target name exists, it cannot have a separate | |||
security policy from the parent directory, | security policy from the parent directory, | |||
and the security policy of the parent was | and the security policy of the parent was | |||
checked when its filehandle was injected into | checked when its filehandle was injected into | |||
the COMPOUND request's operations stream (for | the COMPOUND request's operations stream (for | |||
similar reasons, an OPEN operation that creates | similar reasons, an OPEN operation that creates | |||
the target MUST NOT return NFS4ERR_WRONGSEC). If | the target <bcp14>MUST NOT</bcp14> return NFS4ERR_WRONGSEC). If | |||
the target name exists, while it might have a | the target name exists, while it might have a | |||
separate security policy, that is irrelevant | separate security policy, that is irrelevant | |||
because CREATE MUST return NFS4ERR_EXIST. | because CREATE <bcp14>MUST</bcp14> return NFS4ERR_EXIST. | |||
The rationale for REMOVE is that while that | The rationale for REMOVE is that while that | |||
target might have a separate security policy, the | target might have a separate security policy, the | |||
target is going to be removed, and so the | target is going to be removed, and so the | |||
security policy of the parent trumps that of the | security policy of the parent trumps that of the | |||
object being removed. RENAME and LINK MAY return | object being removed. RENAME and LINK <bcp14>MAY</bcp14> return | |||
NFS4ERR_WRONGSEC, but the NFS4ERR_WRONGSEC error | NFS4ERR_WRONGSEC, but the NFS4ERR_WRONGSEC error | |||
applies only to the saved filehandle (see <xref | applies only to the saved filehandle (see <xref target="link_rename" f | |||
target="link_rename"/>). Any NFS4ERR_WRONGSEC | ormat="default"/>). Any NFS4ERR_WRONGSEC | |||
error on the current filehandle used by LINK and | error on the current filehandle used by LINK and | |||
RENAME MUST be returned by the PUTFH, PUTPUBFH, | RENAME <bcp14>MUST</bcp14> be returned by the PUTFH, PUTPUBFH, | |||
PUTROOTFH, or RESTOREFH operation that injected | PUTROOTFH, or RESTOREFH operation that injected | |||
the current filehandle. | the current filehandle. | |||
</t> | </t> | |||
<t> | <t> | |||
With the exception of LINK and RENAME, | With the exception of LINK and RENAME, | |||
the set of operations that can return NFS4ERR_WRONGSEC | the set of operations that can return NFS4ERR_WRONGSEC | |||
represents the point at which the client can inject a | represents the point at which the client can inject a | |||
filehandle into the "current filehandle" at the server. The | filehandle into the "current filehandle" at the server. The | |||
filehandle is either provided by the client (PUTFH, PUTPUBFH, | filehandle is either provided by the client (PUTFH, PUTPUBFH, | |||
PUTROOTFH), generated as a result of a name-to-filehandle | PUTROOTFH), generated as a result of a name-to-filehandle | |||
translation (LOOKUP and OPEN), or generated from the saved filehandle | translation (LOOKUP and OPEN), or generated from the saved filehandle | |||
via RESTOREFH. As <xref target="PUTFHplusSAVEFH"/> states, | via RESTOREFH. As <xref target="PUTFHplusSAVEFH" format="default"/> st | |||
a put filehandle operation followed by SAVEFH MUST NOT | ates, | |||
a put filehandle operation followed by SAVEFH <bcp14>MUST NOT</bcp14> | ||||
return NFS4ERR_WRONGSEC. Thus, the RESTOREFH operation, under | return NFS4ERR_WRONGSEC. Thus, the RESTOREFH operation, under | |||
certain conditions (see <xref target="putfh_series"/>), is | certain conditions (see <xref target="putfh_series" format="default"/> ), is | |||
permitted to return NFS4ERR_WRONGSEC so that security policies | permitted to return NFS4ERR_WRONGSEC so that security policies | |||
can be honored. | can be honored. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
The READDIR operation will not directly return the | The READDIR operation will not directly return the | |||
NFS4ERR_WRONGSEC error. However, if the READDIR request | NFS4ERR_WRONGSEC error. However, if the READDIR request | |||
included a request for attributes, it is possible that the | included a request for attributes, it is possible that the | |||
READDIR request's security triple did not match that of a | READDIR request's security triple did not match that of a | |||
directory entry. If this is the case and the client has | directory entry. If this is the case and the client has | |||
requested the rdattr_error attribute, the server will return the | requested the rdattr_error attribute, the server will return the | |||
NFS4ERR_WRONGSEC error in rdattr_error for the entry. | NFS4ERR_WRONGSEC error in rdattr_error for the entry. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
To resolve an error return of | To resolve an error return of | |||
NFS4ERR_WRONGSEC, the client does the following: | NFS4ERR_WRONGSEC, the client does the following: | |||
</t> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <li> | |||
<list style="symbols"> | ||||
<t> | ||||
For LOOKUP and OPEN, the client will use SECINFO with the | For LOOKUP and OPEN, the client will use SECINFO with the | |||
same current filehandle and name as provided in the | same current filehandle and name as provided in the | |||
original LOOKUP or OPEN to enumerate the available security | original LOOKUP or OPEN to enumerate the available security | |||
triples. | triples. | |||
</t> | </li> | |||
<t> | <li> | |||
For the rdattr_error, the client will use | For the rdattr_error, the client will use | |||
SECINFO with the same current filehandle | SECINFO with the same current filehandle | |||
as provided in the original READDIR. The | as provided in the original READDIR. The | |||
name passed to SECINFO will be that of the | name passed to SECINFO will be that of the | |||
directory entry (as returned from READDIR) | directory entry (as returned from READDIR) | |||
that had the NFS4ERR_WRONGSEC error in the | that had the NFS4ERR_WRONGSEC error in the | |||
rdattr_error attribute. | rdattr_error attribute. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
For PUTFH, PUTROOTFH, PUTPUBFH, | For PUTFH, PUTROOTFH, PUTPUBFH, | |||
RESTOREFH, LINK, and RENAME, the client will | RESTOREFH, LINK, and RENAME, the client will | |||
use SECINFO_NO_NAME { style = | use SECINFO_NO_NAME { style = | |||
SECINFO_STYLE4_CURRENT_FH }. The client | SECINFO_STYLE4_CURRENT_FH }. The client | |||
will prefix the SECINFO_NO_NAME operation | will prefix the SECINFO_NO_NAME operation | |||
with the appropriate PUTFH, PUTPUBFH, | with the appropriate PUTFH, PUTPUBFH, | |||
or PUTROOTFH operation that provides the | or PUTROOTFH operation that provides the | |||
filehandle originally provided by the PUTFH, | filehandle originally provided by the PUTFH, | |||
PUTPUBFH, PUTROOTFH, or RESTOREFH operation. | PUTPUBFH, PUTROOTFH, or RESTOREFH operation. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
NOTE: In NFSv4.0, the client was required | NOTE: In NFSv4.0, the client was required | |||
to use SECINFO, and had to reconstruct the | to use SECINFO, and had to reconstruct the | |||
parent of the original filehandle and the | parent of the original filehandle and the | |||
component name of the original filehandle. The | component name of the original filehandle. The | |||
introduction in NFSv4.1 of SECINFO_NO_NAME | introduction in NFSv4.1 of SECINFO_NO_NAME | |||
obviates the need for reconstruction. | obviates the need for reconstruction. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
For LOOKUPP, the client will | For LOOKUPP, the client will | |||
use SECINFO_NO_NAME { style = | use SECINFO_NO_NAME { style = | |||
SECINFO_STYLE4_PARENT } and provide the | SECINFO_STYLE4_PARENT } and provide the | |||
filehandle that equals the filehandle | filehandle that equals the filehandle | |||
originally provided to LOOKUPP. | originally provided to LOOKUPP. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
See <xref target="SECCON" format="default"/> for a discussion on | ||||
<t> | ||||
See <xref target="SECCON"/> 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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_SETATTR" numbered="true" toc="default"> | |||
$ --> | <name>Operation 34: SETATTR - Set Attributes</name> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <section toc="exclude" anchor="OP_SETATTR_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_SETATTR" title="Operation 34: SETATTR - Set Attributes" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_SETATTR_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct SETATTR4args { | struct SETATTR4args { | |||
/* CURRENT_FH: target object */ | /* CURRENT_FH: target object */ | |||
stateid4 stateid; | stateid4 stateid; | |||
fattr4 obj_attributes; | fattr4 obj_attributes; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_SETATTR_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_SETATTR_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct SETATTR4res { | struct SETATTR4res { | |||
nfsstat4 status; | nfsstat4 status; | |||
bitmap4 attrsset; | bitmap4 attrsset; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_SETATTR_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_SETATTR_DESCRIPTION" title="DESCRIPTION"> | ||||
<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 | |||
the attributes that follow the bitmap in bit order. | the attributes that follow the bitmap in bit order. | |||
</t> | </t> | |||
<t> | <t> | |||
The stateid argument for SETATTR is used to provide byte-range locking | The stateid argument for SETATTR is used to provide byte-range locking | |||
context that is necessary for SETATTR requests that set the size | context that is necessary for SETATTR requests that set the size | |||
attribute. Since setting the size attribute modifies the file's data, | attribute. Since setting the size attribute modifies the file's data, | |||
it has the same locking requirements as a corresponding WRITE. Any | it has the same locking requirements as a corresponding WRITE. Any | |||
SETATTR that sets the size attribute is incompatible with a share | SETATTR that sets the size attribute is incompatible with a share | |||
reservation that specifies OPEN4_SHARE_DENY_WRITE. The area between the o ld | reservation that specifies OPEN4_SHARE_DENY_WRITE. The area between the o ld | |||
end-of-file and the new end-of-file is considered to be modified just | end-of-file and the new end-of-file is considered to be modified just | |||
as would have been the case had the area in question been specified as | as would have been the case had the area in question been specified as | |||
the target of WRITE, for the purpose of checking conflicts with byte-range | the target of WRITE, for the purpose of checking conflicts with byte-range | |||
locks, for those cases in which a server is implementing mandatory | locks, for those cases in which a server is implementing mandatory | |||
byte-range locking behavior. A valid stateid SHOULD always be specified. | byte-range locking behavior. A valid stateid <bcp14>SHOULD</bcp14> always be specified. | |||
When the file size attribute is not set, the special stateid | When the file size attribute is not set, the special stateid | |||
consisting of all bits equal to zero MAY be passed. | consisting of all bits equal to zero <bcp14>MAY</bcp14> be passed. | |||
</t> | </t> | |||
<t> | <t> | |||
On either success or failure of the operation, the server will return | On either success or failure of the operation, the server will return | |||
the attrsset bitmask to represent what (if any) attributes were | the attrsset bitmask to represent what (if any) attributes were | |||
successfully set. The attrsset in the response is a subset of the | successfully set. The attrsset in the response is a subset of the | |||
attrmask field of the obj_attributes field in the argument. | attrmask field of the obj_attributes field in the argument. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_SETATTR_IMPLEMENTATION" title="IMPLEMENTATIO | <section toc="exclude" anchor="OP_SETATTR_IMPLEMENTATION" numbered="true | |||
N"> | "> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
If the request specifies the owner attribute to be set, the server | If the request specifies the owner attribute to be set, the server | |||
SHOULD allow the operation to succeed if the current owner of the | <bcp14>SHOULD</bcp14> allow the operation to succeed if the current owner of the | |||
object matches the value specified in the request. Some servers may | object matches the value specified in the request. Some servers may | |||
be implemented in a way as to prohibit the setting of the owner | be implemented in a way as to prohibit the setting of the owner | |||
attribute unless the requester has privilege to do so. If the server | attribute unless the requester has privilege to do so. If the server | |||
is lenient in this one case of matching owner values, the client | is lenient in this one case of matching owner values, the client | |||
implementation may be simplified in cases of creation of an object | implementation may be simplified in cases of creation of an object | |||
(e.g., an exclusive create via OPEN) | (e.g., an exclusive create via OPEN) | |||
followed by a SETATTR. | followed by a SETATTR. | |||
</t> | </t> | |||
<t> | <t> | |||
The file size attribute is used to request changes | The file size attribute is used to request changes | |||
to the size of a file. A value of zero causes the | to the size of a file. A value of zero causes the | |||
file to be truncated, a value less than the current | file to be truncated, a value less than the current | |||
size of the file causes data from new size to the | size of the file causes data from new size to the | |||
end of the file to be discarded, and a size greater | end of the file to be discarded, and a size greater | |||
than the current size of the file causes logically | than the current size of the file causes logically | |||
zeroed data bytes to be added to the end of the | zeroed data bytes to be added to the end of the | |||
file. Servers are free to implement this using | file. Servers are free to implement this using | |||
unallocated bytes (holes) or allocated data bytes | unallocated bytes (holes) or allocated data bytes | |||
set to zero. Clients should not make any assumptions | set to zero. Clients should not make any assumptions | |||
regarding a server's implementation of this feature, | regarding a server's implementation of this feature, | |||
beyond that the bytes in the affected byte-range returned by | beyond that the bytes in the affected byte-range returned by | |||
READ will be zeroed. Servers MUST support extending | READ will be zeroed. Servers <bcp14>MUST</bcp14> support extending | |||
the file size via SETATTR. | the file size via SETATTR. | |||
</t> | </t> | |||
<t> | <t> | |||
SETATTR is not guaranteed to be atomic. A failed SETATTR may partially | SETATTR is not guaranteed to be atomic. A failed SETATTR may partially | |||
change a file's attributes, hence the reason why the reply always | change a file's attributes, hence the reason why the reply always | |||
includes the status and the list of attributes that were set. | includes the status and the list of attributes that were set. | |||
</t> | </t> | |||
<t> | <t> | |||
If the object whose attributes are being changed has a file delegation | If the object whose attributes are being changed has a file delegation | |||
that is held by a client other than the one doing the SETATTR, | that is held by a client other than the one doing the SETATTR, | |||
the delegation(s) must be recalled, and the | the delegation(s) must be recalled, and the | |||
operation cannot proceed to actually change an attribute | operation cannot proceed to actually change an attribute | |||
until each such delegation is returned | until each such delegation is returned | |||
or revoked. | or revoked. | |||
In all cases in which delegations are recalled, the server | In all cases in which delegations are recalled, the server | |||
is likely to return one or more NFS4ERR_DELAY errors while the | is likely to return one or more NFS4ERR_DELAY errors while the | |||
delegation(s) remains outstanding, although it might not do that if the | delegation(s) remains outstanding, although it might not do that if the | |||
delegations are returned quickly. | delegations are returned quickly. | |||
</t> | </t> | |||
<t> | <t> | |||
If the object whose attributes are being set is a directory | If the object whose attributes are being set is a directory | |||
and another client holds a directory delegation for that | and another client holds a directory delegation for that | |||
directory, then if enabled, asynchronous notifications will be generated | directory, then if enabled, asynchronous notifications will be generated | |||
when the set of attributes changed has a non-null intersection | when the set of attributes changed has a non-null intersection | |||
with the set of attributes for which notification is requested. | with the set of attributes for which notification is requested. | |||
Notifications of type NOTIFY4_CHANGE_DIR_ATTRS will be sent to | Notifications of type NOTIFY4_CHANGE_DIR_ATTRS will be sent to | |||
the appropriate client(s), but the SETATTR is not delayed by | the appropriate client(s), but the SETATTR is not delayed by | |||
waiting for these notifications to be sent. | waiting for these notifications to be sent. | |||
</t> | </t> | |||
<t> | <t> | |||
If the object whose attributes are being set is a member of | If the object whose attributes are being set is a member of | |||
the directory for which another client holds a directory delegation, | the directory for which another client holds a directory delegation, | |||
then asynchronous notifications will be generated | then asynchronous notifications will be generated | |||
when the set of attributes changed has a non-null intersection | when the set of attributes changed has a non-null intersection | |||
with the set of attributes for which notification is requested. | with the set of attributes for which notification is requested. | |||
Notifications of type NOTIFY4_CHANGE_CHILD_ATTRS will be sent to | Notifications of type NOTIFY4_CHANGE_CHILD_ATTRS will be sent to | |||
the appropriate clients, but the SETATTR is not delayed by | the appropriate clients, but the SETATTR is not delayed by | |||
waiting for these notifications to be sent. | waiting for these notifications to be sent. | |||
</t> | </t> | |||
<t> | <t> | |||
Changing the size of a file with SETATTR indirectly | Changing the size of a file with SETATTR indirectly | |||
changes the time_modify and change attributes. | changes the time_modify and change attributes. | |||
A client must account for this as size changes can | A client must account for this as size changes can | |||
result in data deletion. | result in data deletion. | |||
</t> | </t> | |||
<t> | <t> | |||
The attributes time_access_set and time_modify_set are write-only | The attributes time_access_set and time_modify_set are write-only | |||
attributes constructed as a switched union so the client can direct | attributes constructed as a switched union so the client can direct | |||
the server in setting the time values. If the switched union | the server in setting the time values. If the switched union | |||
specifies SET_TO_CLIENT_TIME4, the client has provided an nfstime4 to | specifies SET_TO_CLIENT_TIME4, the client has provided an nfstime4 to | |||
be used for the operation. If the switch union does not specify | be used for the operation. If the switch union does not specify | |||
SET_TO_CLIENT_TIME4, the server is to use its current time for the | SET_TO_CLIENT_TIME4, the server is to use its current time for the | |||
SETATTR operation. | SETATTR operation. | |||
</t> | </t> | |||
<t> | <t> | |||
If server and client times differ, programs that compare client time | If server and client times differ, programs that compare client time | |||
to file times can break. A time synchronization protocol should be used to | to file times can break. A time synchronization protocol should be used to | |||
limit client/server time skew. | limit client/server time skew. | |||
</t> | </t> | |||
<t> | <t> | |||
Use of a COMPOUND containing a VERIFY operation specifying only the | Use of a COMPOUND containing a VERIFY operation specifying only the | |||
change attribute, immediately followed by a SETATTR, provides a means | change attribute, immediately followed by a SETATTR, provides a means | |||
whereby a client may specify a request that emulates the functionality | whereby a client may specify a request that emulates the functionality | |||
of the SETATTR guard mechanism of NFSv3. Since the function | of the SETATTR guard mechanism of NFSv3. Since the function | |||
of the guard mechanism is to avoid changes to the file attributes | of the guard mechanism is to avoid changes to the file attributes | |||
based on stale information, delays between checking of the guard | based on stale information, delays between checking of the guard | |||
condition and the setting of the attributes have the potential to | condition and the setting of the attributes have the potential to | |||
compromise this function, as would the corresponding delay in the | compromise this function, as would the corresponding delay in the | |||
NFSv4 emulation. Therefore, NFSv4.1 servers SHOULD take | NFSv4 emulation. Therefore, NFSv4.1 servers <bcp14>SHOULD</bcp14> take | |||
care to avoid such delays, to the degree possible, when executing such | care to avoid such delays, to the degree possible, when executing such | |||
a request. | a request. | |||
</t> | </t> | |||
<t> | <t> | |||
If the server does not support an attribute as requested by the | If the server does not support an attribute as requested by the | |||
client, the server SHOULD return NFS4ERR_ATTRNOTSUPP. | client, the server <bcp14>SHOULD</bcp14> return NFS4ERR_ATTRNOTSUPP. | |||
</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 MUST NOT include attribute bits not requested to be | cases. That mask <bcp14>MUST NOT</bcp14> include attribute bits not reque sted 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 MUST be NFS4_OK. | reply are equal, the status field in the reply <bcp14>MUST</bcp14> be NFS4 | |||
</t> | _OK. | |||
</section> | </t> | |||
</section> | </section> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | </section> | |||
$ --> | <section anchor="OP_VERIFY" numbered="true" toc="default"> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <name>Operation 37: VERIFY - Verify Same Attributes</name> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <section toc="exclude" anchor="OP_VERIFY_ARGUMENTS" numbered="true"> | |||
<section anchor="OP_VERIFY" title="Operation 37: VERIFY - Verify Same Attributes | <name>ARGUMENTS</name> | |||
" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_VERIFY_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct VERIFY4args { | struct VERIFY4args { | |||
/* CURRENT_FH: object */ | /* CURRENT_FH: object */ | |||
fattr4 obj_attributes; | fattr4 obj_attributes; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_VERIFY_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_VERIFY_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct VERIFY4res { | struct VERIFY4res { | |||
nfsstat4 status; | nfsstat4 status; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_VERIFY_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_VERIFY_DESCRIPTION" title="DESCRIPTION"> | ||||
<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 | |||
error NFS4ERR_NOT_SAME must be returned. The current filehandle | error NFS4ERR_NOT_SAME must be returned. The current filehandle | |||
retains its value after successful completion of the operation. | retains its value after successful completion of the operation. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_VERIFY_IMPLEMENTATION" title="IMPLEMENTATION | <section toc="exclude" anchor="OP_VERIFY_IMPLEMENTATION" numbered="true" | |||
"> | > | |||
<t> | <name>IMPLEMENTATION</name> | |||
<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. | |||
<figure> | </t> | |||
<artwork> | <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) | REMOVE (file name)]]></sourcecode> | |||
</artwork> | <t> | |||
</figure> | ||||
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> | |||
<t> | <t> | |||
In the case that a RECOMMENDED attribute is specified in the VERIFY | In the case that a <bcp14>RECOMMENDED</bcp14> attribute is specified in th | |||
e VERIFY | ||||
operation and the server does not support that attribute for the | operation and the server does not support that attribute for the | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_WRITE" numbered="true" toc="default"> | |||
$ --> | <name>Operation 38: WRITE - Write to File</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_WRITE_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="OP_WRITE" title="Operation 38: WRITE - Write to File" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_WRITE_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_WRITE_RESULTS" numbered="true"> | |||
</figure> | <name>RESULTS</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_WRITE_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
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: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_WRITE_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_WRITE_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The WRITE operation is used to write data to a regular file. The | The WRITE operation is used to write data to a regular file. The | |||
target file is specified by the current filehandle. The offset | target file is specified by the current filehandle. The offset | |||
specifies the offset where the data should be written. An offset of zero | specifies the offset where the data should be written. An offset of zero | |||
specifies that the write should start at the beginning of the | specifies that the write should start at the beginning of the | |||
file. The count, as encoded as part of the opaque data parameter, | file. The count, as encoded as part of the opaque data parameter, | |||
represents the number of bytes of data that are to be written. If the | represents the number of bytes of data that are to be written. If the | |||
count is zero, the WRITE will succeed and return a count of zero subject t o permissions checking. The server MAY | count is zero, the WRITE will succeed and return a count of zero subject t o permissions checking. The server <bcp14>MAY</bcp14> | |||
write fewer bytes than requested by the client. | write fewer bytes than requested by the client. | |||
</t> | </t> | |||
<t> | <t> | |||
The client specifies with the stable parameter the method | The client specifies with the stable parameter the method | |||
of how the data is to be processed by the server. If stable is | of how the data is to be processed by the server. If stable is | |||
FILE_SYNC4, the server MUST commit the data written plus all | FILE_SYNC4, the server <bcp14>MUST</bcp14> commit the data written plus al l | |||
file system metadata to stable storage before returning results. This | file system metadata to stable storage before returning results. This | |||
corresponds to the NFSv2 protocol semantics. Any other | corresponds to the NFSv2 protocol semantics. Any other | |||
behavior constitutes a protocol violation. If stable is DATA_SYNC4, | behavior constitutes a protocol violation. If stable is DATA_SYNC4, | |||
then the server MUST commit all of the data to stable storage and | then the server <bcp14>MUST</bcp14> commit all of the data to stable stora ge and | |||
enough of the metadata to retrieve the data before returning. The | enough of the metadata to retrieve the data before returning. The | |||
server implementor is free to implement DATA_SYNC4 in the same fashion | server implementor is free to implement DATA_SYNC4 in the same fashion | |||
as FILE_SYNC4, but with a possible performance drop. If stable is | as FILE_SYNC4, but with a possible performance drop. If stable is | |||
UNSTABLE4, the server is free to commit any part of the data and the | UNSTABLE4, the server is free to commit any part of the data and the | |||
metadata to stable storage, including all or none, before returning a | metadata to stable storage, including all or none, before returning a | |||
reply to the client. There is no guarantee whether or when any | reply to the client. There is no guarantee whether or when any | |||
uncommitted data will subsequently be committed to stable storage. The | uncommitted data will subsequently be committed to stable storage. The | |||
only guarantees made by the server are that it will not destroy any | only guarantees made by the server are that it will not destroy any | |||
data without changing the value of writeverf and that it will not commit | data without changing the value of writeverf and that it will not commit | |||
the data and metadata at a level less than that requested by the | the data and metadata at a level less than that requested by the | |||
client. | client. | |||
</t> | </t> | |||
<t> | <t> | |||
Except when special stateids are used, the | Except when special stateids are used, the | |||
stateid value for a WRITE request represents a value returned from | stateid value for a WRITE request represents a value returned from | |||
a previous byte-range LOCK or OPEN request or the stateid | a previous byte-range LOCK or OPEN request or the stateid | |||
associated with a delegation. The stateid identifies the associated | associated with a delegation. The stateid identifies the associated | |||
owners if any and is | owners if any and is | |||
used by the server to verify that the associated locks are still | used by the server to verify that the associated locks are still | |||
valid (e.g., have not been revoked). | valid (e.g., have not been revoked). | |||
</t> | </t> | |||
<t> | <t> | |||
Upon successful completion, the following results are returned. The | Upon successful completion, the following results are returned. The | |||
count result is the number of bytes of data written to the file. The | count result is the number of bytes of data written to the file. The | |||
server may write fewer bytes than requested. If so, the actual number | server may write fewer bytes than requested. If so, the actual number | |||
of bytes written starting at location, offset, is returned. | of bytes written starting at location, offset, is returned. | |||
</t> | </t> | |||
<t> | <t> | |||
The server also returns an indication of the level of commitment of | The server also returns an indication of the level of commitment of | |||
the data and metadata via committed. | the data and metadata via committed. | |||
Per <xref target="stable_committed"/>, | Per <xref target="stable_committed" format="default"/>, | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
The server MAY commit the data at a stronger level | <li> | |||
The server <bcp14>MAY</bcp14> commit the data at a stronger level | ||||
than requested. | than requested. | |||
</t> | </li> | |||
<li> | ||||
<t> | The server <bcp14>MUST</bcp14> commit the data at a level at | |||
The server MUST commit the data at a level at | ||||
least as high as that committed. | least as high as that committed. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | ||||
<texttable anchor="stable_committed"> | ||||
<preamble> | ||||
Valid combinations of the fields stable in the request and committed in | ||||
the reply. | ||||
</preamble> | ||||
<ttcol>stable</ttcol> | ||||
<ttcol>committed</ttcol> | ||||
<c>UNSTABLE4</c> <c>FILE_SYNC4, DATA_SYNC4, UNSTABLE4</c> | ||||
<c>DATA_SYNC4</c> <c>FILE_SYNC4, DATA_SYNC4</c> | ||||
<c>FILE_SYNC4</c> <c>FILE_SYNC4</c> | ||||
</texttable> | ||||
<t> | <table anchor="stable_committed" align="center"> | |||
<name>Valid Combinations of the Fields Stable in the Request and Commi | ||||
tted in the Reply</name> | ||||
<thead> | ||||
<tr> | ||||
<th align="left">stable</th> | ||||
<th align="left">committed</th> | ||||
</tr> | ||||
</thead> | ||||
<tbody> | ||||
<tr> | ||||
<td align="left">UNSTABLE4</td> | ||||
<td align="left">FILE_SYNC4, DATA_SYNC4, UNSTABLE4</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">DATA_SYNC4</td> | ||||
<td align="left">FILE_SYNC4, DATA_SYNC4</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">FILE_SYNC4</td> | ||||
<td align="left">FILE_SYNC4</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
<t> | ||||
The final portion of the result is the field | The final portion of the result is the field | |||
writeverf. This field is the write verifier and is a | writeverf. This field is the write verifier and is a | |||
cookie that the client can use to determine whether | cookie that the client can use to determine whether | |||
a server has changed instance state (e.g., server | a server has changed instance state (e.g., server | |||
restart) between a call to WRITE and a subsequent | restart) between a call to WRITE and a subsequent | |||
call to either WRITE or COMMIT. This cookie MUST be | call to either WRITE or COMMIT. This cookie <bcp14>MUST</bcp14> be | |||
unchanged during a single instance of the NFSv4.1 | unchanged during a single instance of the NFSv4.1 | |||
server and MUST be unique between instances of the | server and <bcp14>MUST</bcp14> be unique between instances of the | |||
NFSv4.1 server. If the cookie changes, then the | NFSv4.1 server. If the cookie changes, then the | |||
client MUST assume that any data written with an | client <bcp14>MUST</bcp14> assume that any data written with an | |||
UNSTABLE4 value for committed and an old writeverf in the reply | UNSTABLE4 value for committed and an old writeverf in the reply | |||
has been lost and will need to be recovered. | has been lost and will need to be recovered. | |||
</t> | </t> | |||
<t> | <t> | |||
If a client writes data to the server with the stable argument set to | If a client writes data to the server with the stable argument set to | |||
UNSTABLE4 and the reply yields a committed response of DATA_SYNC4 or | UNSTABLE4 and the reply yields a committed response of DATA_SYNC4 or | |||
UNSTABLE4, the client will follow up some time in the future with a | UNSTABLE4, the client will follow up some time in the future with a | |||
COMMIT operation to synchronize outstanding asynchronous data and | COMMIT operation to synchronize outstanding asynchronous data and | |||
metadata with the server's stable storage, barring client error. It is | metadata with the server's stable storage, barring client error. It is | |||
possible that due to client crash or other error that a subsequent | possible that due to client crash or other error that a subsequent | |||
COMMIT will not be received by the server. | COMMIT will not be received by the server. | |||
</t> | </t> | |||
<t> | <t> | |||
For a WRITE with a stateid value of all bits equal to zero, the server MAY | For a WRITE with a stateid value of all bits equal to zero, the server <bc | |||
allow | p14>MAY</bcp14> allow | |||
the WRITE to be serviced subject to mandatory byte-range locks or the | the WRITE to be serviced subject to mandatory byte-range locks or the | |||
current share deny modes for the file. For a WRITE with a stateid | current share deny modes for the file. For a WRITE with a stateid | |||
value of all bits equal to 1, the server MUST NOT allow the WRITE operatio n to | value of all bits equal to 1, the server <bcp14>MUST NOT</bcp14> allow the WRITE operation to | |||
bypass locking checks at the server and otherwise is | bypass locking checks at the server and otherwise is | |||
treated as if a stateid of all bits equal to zero were used. | treated as if a stateid of all bits equal to zero were used. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_WRITE_IMPLEMENTATION" title="IMPLEMENTATION" | <section toc="exclude" anchor="OP_WRITE_IMPLEMENTATION" numbered="true"> | |||
> | <name>IMPLEMENTATION</name> | |||
<t> | <t> | |||
It is possible for the server to write fewer bytes of data than | It is possible for the server to write fewer bytes of data than | |||
requested by the client. In this case, the server SHOULD NOT return | requested by the client. In this case, the server <bcp14>SHOULD NOT</bcp1 4> return | |||
an error unless no data was written at all. If the server writes less | an error unless no data was written at all. If the server writes less | |||
than the number of bytes specified, the client will need to send another | than the number of bytes specified, the client will need to send another | |||
WRITE to write the remaining data. | WRITE to write the remaining data. | |||
</t> | </t> | |||
<t> | <t> | |||
It is assumed that the act of writing data to | It is assumed that the act of writing data to | |||
a file will cause the time_modified and change | a file will cause the time_modified and change | |||
attributes of the file to be updated. However, | attributes of the file to be updated. However, | |||
these attributes SHOULD NOT be changed | these attributes <bcp14>SHOULD NOT</bcp14> be changed | |||
unless the contents of the file are changed. Thus, | unless the contents of the file are changed. Thus, | |||
a WRITE request with count set to zero SHOULD NOT cause | a WRITE request with count set to zero <bcp14>SHOULD NOT</bcp14> cause | |||
the time_modified and change attributes of the file to be updated. | the time_modified and change attributes of the file to be updated. | |||
</t> | </t> | |||
<t> | <t> | |||
Stable storage is persistent storage that survives: | Stable storage is persistent storage that survives: | |||
</t> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<list style="numbers"> | <li> | |||
<t> | ||||
Repeated power failures. | Repeated power failures. | |||
</t> | </li> | |||
<t> | <li> | |||
Hardware failures (of any board, power supply, etc.). | Hardware failures (of any board, power supply, etc.). | |||
</t> | </li> | |||
<t> | <li> | |||
Repeated software crashes and restarts. | Repeated software crashes and restarts. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | <t> | |||
<t> | ||||
This definition does not address failure of the stable storage module | This definition does not address failure of the stable storage module | |||
itself. | itself. | |||
</t> | </t> | |||
<t> | <t> | |||
The verifier is defined to allow a client to detect | The verifier is defined to allow a client to detect | |||
different instances of an NFSv4.1 protocol server | different instances of an NFSv4.1 protocol server | |||
over which cached, uncommitted data may be lost. In | over which cached, uncommitted data may be lost. In | |||
the most likely case, the verifier allows the client | the most likely case, the verifier allows the client | |||
to detect server restarts. This information is | to detect server restarts. This information is | |||
required so that the client can safely determine | required so that the client can safely determine | |||
whether the server could have lost cached data. | whether the server could have lost cached data. | |||
If the server fails unexpectedly and the client has | If the server fails unexpectedly and the client has | |||
uncommitted data from previous WRITE requests (done | uncommitted data from previous WRITE requests (done | |||
with the stable argument set to UNSTABLE4 and in | with the stable argument set to UNSTABLE4 and in | |||
which the result committed was returned as UNSTABLE4 | which the result committed was returned as UNSTABLE4 | |||
as well), the server might not have flushed cached | as well), the server might not have flushed cached | |||
data to stable storage. The burden of recovery is | data to stable storage. The burden of recovery is | |||
on the client, and the client will need to retransmit | on the client, and the client will need to retransmit | |||
the data to the server. | the data to the server. | |||
</t> | </t> | |||
<t> | <t> | |||
A suggested verifier would be to use the time that | A suggested verifier would be to use the time that | |||
the server was last started (if restarting the server | the server was last started (if restarting the server | |||
results in lost buffers). | results in lost buffers). | |||
</t> | </t> | |||
<t> | <t> | |||
The reply's committed field allows the client to do more | The reply's committed field allows the client to do more | |||
effective caching. If the server is committing all WRITE requests to | effective caching. If the server is committing all WRITE requests to | |||
stable storage, then it SHOULD return with committed set to FILE_SYNC4, | stable storage, then it <bcp14>SHOULD</bcp14> return with committed set to FILE_SYNC4, | |||
regardless of the value of the stable field in the arguments. A server | regardless of the value of the stable field in the arguments. A server | |||
that uses an NVRAM accelerator may choose to implement this policy. | that uses an NVRAM accelerator may choose to implement this policy. | |||
The client can use this to increase the effectiveness of the cache by | The client can use this to increase the effectiveness of the cache by | |||
discarding cached data that has already been committed on the server. | discarding cached data that has already been committed on the server. | |||
</t> | </t> | |||
<t> | <t> | |||
Some implementations may return NFS4ERR_NOSPC instead | Some implementations may return NFS4ERR_NOSPC instead | |||
of NFS4ERR_DQUOT when a user's quota is exceeded. | of NFS4ERR_DQUOT when a user's quota is exceeded. | |||
</t> | </t> | |||
<t> | <t> | |||
In the case that the current filehandle is of | In the case that the current filehandle is of | |||
type NF4DIR, the server will return NFS4ERR_ISDIR. | type NF4DIR, the server will return NFS4ERR_ISDIR. | |||
If the current file is a symbolic link, the error | If the current file is a symbolic link, the error | |||
NFS4ERR_SYMLINK will be returned. Otherwise, if the | NFS4ERR_SYMLINK will be returned. Otherwise, if the | |||
current filehandle does not designate an ordinary | current filehandle does not designate an ordinary | |||
file, the server will return NFS4ERR_WRONG_TYPE. | file, the server will return NFS4ERR_WRONG_TYPE. | |||
</t> | </t> | |||
<t> | <t> | |||
If mandatory byte-range locking is in effect for the file, | If mandatory byte-range locking is in effect for the file, | |||
and the corresponding byte-range of the data to | and the corresponding byte-range of the data to | |||
be written to the file is READ_LT or WRITE_LT locked by | be written to the file is READ_LT or WRITE_LT locked by | |||
an owner that is not associated with the stateid, | an owner that is not associated with the stateid, | |||
the server MUST return NFS4ERR_LOCKED. If so, | the server <bcp14>MUST</bcp14> return NFS4ERR_LOCKED. If so, | |||
the client MUST check if the owner corresponding | the client <bcp14>MUST</bcp14> check if the owner corresponding | |||
to the stateid used with the WRITE operation has a | to the stateid used with the WRITE operation has a | |||
conflicting READ_LT lock that overlaps with the byte-range | conflicting READ_LT lock that overlaps with the byte-range | |||
that was to be written. If the stateid's owner has | that was to be written. If the stateid's owner has | |||
no conflicting READ_LT lock, then the client SHOULD try | no conflicting READ_LT lock, then the client <bcp14>SHOULD</bcp14> try | |||
to get the appropriate write byte-range lock via the | to get the appropriate write byte-range lock via the | |||
LOCK operation before re-attempting the WRITE. When | LOCK operation before re-attempting the WRITE. When | |||
the WRITE completes, the client SHOULD release the | the WRITE completes, the client <bcp14>SHOULD</bcp14> release the | |||
byte-range lock via LOCKU. | byte-range lock via LOCKU. | |||
</t> | </t> | |||
<t> | <t> | |||
If the stateid's owner had a conflicting READ_LT lock, then the client | If the stateid's owner had a conflicting READ_LT lock, then the client | |||
has no choice but to return an error to the application that attempted | has no choice but to return an error to the application that attempted | |||
the WRITE. The reason is that since the stateid's owner had a READ_LT | the WRITE. The reason is that since the stateid's owner had a READ_LT | |||
lock, either the server attempted to temporarily effectively upgrade | lock, either the server attempted to temporarily effectively upgrade | |||
this READ_LT lock to a WRITE_LT lock or the server has no upgrade | this READ_LT lock to a WRITE_LT lock or the server has no upgrade | |||
capability. If the server attempted to upgrade the READ_LT lock and | capability. If the server attempted to upgrade the READ_LT lock and | |||
failed, it is pointless for the client to re-attempt the upgrade via | failed, it is pointless for the client to re-attempt the upgrade via | |||
the LOCK operation, because there might be another client also trying | the LOCK operation, because there might be another client also trying | |||
to upgrade. If two clients are blocked trying to upgrade the same lock, | to upgrade. If two clients are blocked trying to upgrade the same lock, | |||
the clients deadlock. If the server has no upgrade capability, then | the clients deadlock. If the server has no upgrade capability, then | |||
it is pointless to try a LOCK operation to upgrade. | it is pointless to try a LOCK operation to upgrade. | |||
</t> | </t> | |||
<t> | <t> | |||
If one or more other clients have delegations for the file being | If one or more other clients have delegations for the file being | |||
written, those delegations MUST be recalled, and the | written, those delegations <bcp14>MUST</bcp14> be recalled, and the | |||
operation cannot proceed until those delegations are returned | operation cannot proceed until those delegations are returned | |||
or revoked. Except where this | or revoked. 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. | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_BACKCHANNEL_CTL" numbered="true" toc="default"> | |||
$ --> | <name>Operation 40: BACKCHANNEL_CTL - Backchannel Control</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_BACKCHANNEL_CTL_ARGUMENT" numbered="tr | |||
<!-- Copyright (C) The Internet Society (2006) --> | ue"> | |||
<section anchor="OP_BACKCHANNEL_CTL" title="Operation 40: BACKCHANNEL_CTL - Back | <name>ARGUMENT</name> | |||
channel Control" > | <sourcecode type="xdr"><![CDATA[ | |||
typedef opaque gsshandle4_t<>; | ||||
<section toc="exclude" anchor="OP_BACKCHANNEL_CTL_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_BACKCHANNEL_CTL_RESULT" numbered="true | |||
</figure> | "> | |||
</section> | <name>RESULT</name> | |||
<section toc="exclude" anchor="OP_BACKCHANNEL_CTL_RESULT" title="RESULT"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
struct BACKCHANNEL_CTL4res { | struct BACKCHANNEL_CTL4res { | |||
nfsstat4 bcr_status; | nfsstat4 bcr_status; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_BACKCHANNEL_CTL_DESCRIPTION" numbered= | |||
</figure> | "true"> | |||
</section> | <name>DESCRIPTION</name> | |||
<section toc="exclude" anchor="OP_BACKCHANNEL_CTL_DESCRIPTION" title="DESCRIPT | <t> | |||
ION"> | ||||
<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 | |||
backchannel. | backchannel. | |||
</t> | </t> | |||
<t> | <t> | |||
The arguments of the BACKCHANNEL_CTL call are | The arguments of the BACKCHANNEL_CTL call are | |||
a subset of the CREATE_SESSION parameters. | a subset of the CREATE_SESSION parameters. | |||
In the arguments of BACKCHANNEL_CTL, the | In the arguments of BACKCHANNEL_CTL, the | |||
bca_cb_program field and bca_sec_parms fields | bca_cb_program field and bca_sec_parms fields | |||
correspond respectively to the csa_cb_program and | correspond respectively to the csa_cb_program and | |||
csa_sec_parms fields of the arguments of CREATE_SESSION | csa_sec_parms fields of the arguments of CREATE_SESSION | |||
(<xref target="OP_CREATE_SESSION"/>). | (<xref target="OP_CREATE_SESSION" format="default"/>). | |||
</t> | </t> | |||
<t> | <t> | |||
BACKCHANNEL_CTL MUST appear in a COMPOUND that starts | BACKCHANNEL_CTL <bcp14>MUST</bcp14> appear in a COMPOUND that starts | |||
with SEQUENCE. | with SEQUENCE. | |||
</t> | </t> | |||
<t> | <t> | |||
If the RPCSEC_GSS handle identified by | If the RPCSEC_GSS handle identified by | |||
gcbp_handle_from_server does not exist on the server, | gcbp_handle_from_server does not exist on the server, | |||
the server MUST 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_m | |||
If an RPCSEC_GSS handle is using the SSV context (see <xref | ech" format="default"/>), then because each SSV RPCSEC_GSS | |||
target="ssv_mech"/>), 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 | considerations specific to this situation discussed in <xref target="rpcs | |||
target="rpcsec_ssv_consider"/>. | ec_ssv_consider" format="default"/>. | |||
</t> | </t> | |||
</section> | ||||
</section> | </section> | |||
</section> | <section anchor="OP_BIND_CONN_TO_SESSION" numbered="true" toc="default"> | |||
<name>Operation 41: BIND_CONN_TO_SESSION - Associate Connection with Ses | ||||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | sion</name> | |||
$ --> | <section toc="exclude" anchor="OP_BIND_CONN_TO_SESSION_ARGUMENT" numbere | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | d="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENT</name> | |||
<section anchor="OP_BIND_CONN_TO_SESSION" title="Operation 41: BIND_CONN_TO_SESS | <sourcecode type="xdr"><![CDATA[ | |||
ION - Associate Connection with Session" > | ||||
<section toc="exclude" | ||||
anchor="OP_BIND_CONN_TO_SESSION_ARGUMENT" | ||||
title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_BIND_CONN_TO_SESSION_RESULT" numbered= | |||
</figure> | "true"> | |||
</section> | <name>RESULT</name> | |||
<section toc="exclude" anchor="OP_BIND_CONN_TO_SESSION_RESULT" title="RESULT"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
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 34984 ¶ | skipping to change at line 35082 ¶ | |||
}; | }; | |||
union BIND_CONN_TO_SESSION4res | union BIND_CONN_TO_SESSION4res | |||
switch (nfsstat4 bctsr_status) { | switch (nfsstat4 bctsr_status) { | |||
case NFS4_OK: | case NFS4_OK: | |||
BIND_CONN_TO_SESSION4resok | BIND_CONN_TO_SESSION4resok | |||
bctsr_resok4; | bctsr_resok4; | |||
default: void; | default: void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_BIND_CONN_TO_SESSION_DESCRIPTION" numb | |||
</figure> | ered="true"> | |||
</section> | <name>DESCRIPTION</name> | |||
<section toc="exclude" anchor="OP_BIND_CONN_TO_SESSION_DESCRIPTION" title="DES | <t> | |||
CRIPTION"> | ||||
<t> | ||||
BIND_CONN_TO_SESSION is used to associate additional connections with a | BIND_CONN_TO_SESSION is used to associate additional connections with a | |||
session. It MUST be used on the connection being associated with the sessi on. It MUST | session. It <bcp14>MUST</bcp14> be used on the connection being associated with the session. It <bcp14>MUST</bcp14> | |||
be the only operation in the COMPOUND procedure. If | be the only operation in the COMPOUND procedure. If | |||
SP4_NONE (<xref target="OP_EXCHANGE_ID" />) state protection | SP4_NONE (<xref target="OP_EXCHANGE_ID" format="default"/>) state protecti on | |||
is used, any principal, | is used, any principal, | |||
security flavor, or RPCSEC_GSS context MAY be used to invoke the operation | security flavor, or RPCSEC_GSS context <bcp14>MAY</bcp14> be used to invok | |||
. | e the operation. | |||
If SP4_MACH_CRED is used, RPCSEC_GSS MUST be used with the | If SP4_MACH_CRED is used, RPCSEC_GSS <bcp14>MUST</bcp14> be used with the | |||
integrity or privacy services, using the principal that | integrity or privacy services, using the principal that | |||
created the client ID. If SP4_SSV is used, RPCSEC_GSS with | created the client ID. If SP4_SSV is used, RPCSEC_GSS with | |||
the SSV GSS mechanism (<xref target="ssv_mech" />) and integrity or | the SSV GSS mechanism (<xref target="ssv_mech" format="default"/>) and int | |||
privacy MUST be used. | egrity or | |||
</t> | privacy <bcp14>MUST</bcp14> be used. | |||
<t> | </t> | |||
<t> | ||||
If, when the client ID was created, the client opted for SP4_NONE | If, when the client ID was created, the client opted for SP4_NONE | |||
state protection, | state protection, | |||
the client is not required to use BIND_CONN_TO_SESSION to associate the | the client is not required to use BIND_CONN_TO_SESSION to associate the | |||
connection with the session, unless | connection with the session, unless | |||
the client wishes to associate the connection with the backchannel. | the client wishes to associate the connection with the backchannel. | |||
When SP4_NONE protection is used, simply sending a COMPOUND | When SP4_NONE protection is used, simply sending a COMPOUND | |||
request with a SEQUENCE operation is sufficient to associate the | request with a SEQUENCE operation is sufficient to associate the | |||
connection with the session specified in SEQUENCE. | connection with the session specified in SEQUENCE. | |||
</t> | </t> | |||
<t> | <t> | |||
The field bctsa_dir indicates whether the client | The field bctsa_dir indicates whether the client | |||
wants to associate the connection with the fore | wants to associate the connection with the fore | |||
channel or the backchannel or both channels. The value | channel or the backchannel or both channels. The value | |||
CDFC4_FORE_OR_BOTH indicates that the client wants to | CDFC4_FORE_OR_BOTH indicates that the client wants to | |||
associate the connection with both the fore channel and backchannel, | associate the connection with both the fore channel and backchannel, | |||
but will accept the connection being associated to | but will accept the connection being associated to | |||
just the fore channel. The value CDFC4_BACK_OR_BOTH | just the fore channel. The value CDFC4_BACK_OR_BOTH | |||
indicates that the client wants to associate with both | indicates that the client wants to associate with both | |||
the fore channel and backchannel, but will accept the | the fore channel and backchannel, but will accept the | |||
connection being associated with just the backchannel. | connection being associated with just the backchannel. | |||
The server replies in bctsr_dir which channel(s) | The server replies in bctsr_dir which channel(s) | |||
the connection is associated with. | the connection is associated with. | |||
If the client specified CDFC4_FORE, the server | If the client specified CDFC4_FORE, the server | |||
MUST return CDFS4_FORE. If the client specified | <bcp14>MUST</bcp14> return CDFS4_FORE. If the client specified | |||
CDFC4_BACK, the server MUST return CDFS4_BACK. If the | CDFC4_BACK, the server <bcp14>MUST</bcp14> return CDFS4_BACK. If the | |||
client specified CDFC4_FORE_OR_BOTH, the server MUST return | client specified CDFC4_FORE_OR_BOTH, the server <bcp14>MUST</bcp14> return | |||
CDFS4_FORE or CDFS4_BOTH. If the client specified | CDFS4_FORE or CDFS4_BOTH. If the client specified | |||
CDFC4_BACK_OR_BOTH, the server MUST return CDFS4_BACK | CDFC4_BACK_OR_BOTH, the server <bcp14>MUST</bcp14> return CDFS4_BACK | |||
or CDFS4_BOTH. | or CDFS4_BOTH. | |||
</t> | </t> | |||
<t> | <t> | |||
See the CREATE_SESSION operation (<xref target="OP_CREATE_SESSION" />), | See the CREATE_SESSION operation (<xref target="OP_CREATE_SESSION" format=" | |||
default"/>), | ||||
and the description of the argument | and the description of the argument | |||
csa_use_conn_in_rdma_mode to understand | csa_use_conn_in_rdma_mode to understand | |||
bctsa_use_conn_in_rdma_mode, and the description of | bctsa_use_conn_in_rdma_mode, and the description of | |||
csr_use_conn_in_rdma_mode to understand bctsr_use_conn_in_rdma_mode. | csr_use_conn_in_rdma_mode to understand bctsr_use_conn_in_rdma_mode. | |||
</t> | </t> | |||
<t> | <t> | |||
Invoking BIND_CONN_TO_SESSION on a connection already associated | Invoking BIND_CONN_TO_SESSION on a connection already associated | |||
with the specified session has no effect, and the server MUST | with the specified session has no effect, and the server <bcp14>MUST</bcp14 > | |||
respond with NFS4_OK, unless the client is demanding changes | respond with NFS4_OK, unless the client is demanding changes | |||
to the set of channels the connection is associated with. If | to the set of channels the connection is associated with. If | |||
so, the server MUST return NFS4ERR_INVAL. | so, the server <bcp14>MUST</bcp14> return NFS4ERR_INVAL. | |||
</t> | ||||
</section> | </t> | |||
<section toc="exclude" anchor="OP_BIND_CONN_TO_SESSION_IMPLEMENTATION" title=" | </section> | |||
IMPLEMENTATION"> | <section toc="exclude" anchor="OP_BIND_CONN_TO_SESSION_IMPLEMENTATION" n | |||
<t> | umbered="true"> | |||
<name>IMPLEMENTATION</name> | ||||
<t> | ||||
If a session's channel loses all connections, depending on | If a session's channel loses all connections, depending on | |||
the client ID's state protection and type of channel, | the client ID's state protection and type of channel, | |||
the client might need to use | the client might need to use | |||
BIND_CONN_TO_SESSION to associate a new connection. If the | BIND_CONN_TO_SESSION to associate a new connection. If the | |||
server restarted and does not keep the reply cache in stable | server restarted and does not keep the reply cache in stable | |||
storage, the server will not recognize the session ID. | storage, the server will not recognize the session ID. | |||
The client will ultimately have to invoke EXCHANGE_ID to | The client will ultimately have to invoke EXCHANGE_ID to | |||
create a new client ID and session. | create a new client ID and session. | |||
</t> | </t> | |||
<t> | <t> | |||
Suppose SP4_SSV state protection is being used, | Suppose SP4_SSV state protection is being used, | |||
and BIND_CONN_TO_SESSION is among the operations | and BIND_CONN_TO_SESSION is among the operations | |||
included in the spo_must_enforce set when the | included in the spo_must_enforce set when the | |||
client ID was created (<xref target="OP_EXCHANGE_ID"/>). | client ID was created (<xref target="OP_EXCHANGE_ID" format="default"/>). | |||
If so, there is an issue if SET_SSV is sent, no response | If so, there is an issue if SET_SSV is sent, no response | |||
is returned, and the last connection associated | is returned, and the last connection associated | |||
with the client ID drops. The client, per | with the client ID drops. The client, per | |||
the sessions model, MUST retry the SET_SSV. But | the sessions model, <bcp14>MUST</bcp14> retry the SET_SSV. But | |||
it needs a new connection to do so, and MUST | it needs a new connection to do so, and <bcp14>MUST</bcp14> | |||
associate that connection with the session via a | associate that connection with the session via a | |||
BIND_CONN_TO_SESSION authenticated with the SSV | BIND_CONN_TO_SESSION authenticated with the SSV | |||
GSS mechanism. The problem is that the RPCSEC_GSS | GSS mechanism. The problem is that the RPCSEC_GSS | |||
message integrity codes use a subkey derived from the SSV as the | message integrity codes use a subkey derived from the SSV as the | |||
key and the | key and the | |||
SSV may have changed. While there are multiple | SSV may have changed. While there are multiple | |||
recovery strategies, a single, general strategy | recovery strategies, a single, general strategy | |||
is described here. | is described here. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The client reconnects. | The client reconnects. | |||
</t> | </li> | |||
<t> | <li> | |||
The client assumes that the SET_SSV was executed, | The client assumes that the SET_SSV was executed, | |||
and so sends BIND_CONN_TO_SESSION with the subkey (derived from | and so sends BIND_CONN_TO_SESSION with the subkey (derived from | |||
the new SSV, i.e., what SET_SSV would have set the SSV to) | the new SSV, i.e., what SET_SSV would have set the SSV to) | |||
used as the key for the RPCSEC_GSS credential message integrity codes. | used as the key for the RPCSEC_GSS credential message integrity codes. | |||
</t> | </li> | |||
<t> | <li> | |||
If the request succeeds, this means that the original attempted SET_SSV | If the request succeeds, this means that the original attempted SET_SSV | |||
did execute successfully. The client re-sends the original | did execute successfully. The client re-sends the original | |||
SET_SSV, which the server will reply to via the | SET_SSV, which the server will reply to via the | |||
reply cache. | reply cache. | |||
</t> | </li> | |||
<t> | <li> | |||
If the server returns an RPC authentication error, | If the server returns an RPC authentication error, | |||
this means that the server's current SSV was not changed | this means that the server's current SSV was not changed | |||
(and the SET_SSV was likely not executed). The client then | (and the SET_SSV was likely not executed). The client then | |||
tries BIND_CONN_TO_SESSION with the subkey derived from the | tries BIND_CONN_TO_SESSION with the subkey derived from the | |||
old SSV as the | old SSV as the | |||
key for the RPCSEC_GSS message integrity codes. | key for the RPCSEC_GSS message integrity codes. | |||
</t> | </li> | |||
<t> | <li> | |||
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. | |||
</t> | </li> | |||
</ul> | ||||
</list> | </section> | |||
</section> | ||||
</t> | <section anchor="OP_EXCHANGE_ID" numbered="true" toc="default"> | |||
</section> | <name>Operation 42: EXCHANGE_ID - Instantiate Client ID</name> | |||
</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) --> | ||||
<section title="Operation 42: EXCHANGE_ID - Instantiate Client ID" | ||||
anchor="OP_EXCHANGE_ID"> | ||||
<t> | <t> | |||
The EXCHANGE_ID operation exchanges long-hand | The EXCHANGE_ID operation exchanges long-hand client and server identi | |||
client and server identifiers | fiers | |||
(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 title="ARGUMENT" | <section anchor="EXID-arg" toc="exclude" numbered="true"> | |||
anchor="EXID-arg" | <name>ARGUMENT</name> | |||
toc="exclude"> | <sourcecode type="xdr"><![CDATA[ | |||
<t> | ||||
<figure> | ||||
<artwork> | ||||
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 35161 ¶ | skipping to change at line 35248 ¶ | |||
const EXCHGID4_FLAG_UPD_CONFIRMED_REC_A = 0x40000000; | const EXCHGID4_FLAG_UPD_CONFIRMED_REC_A = 0x40000000; | |||
const EXCHGID4_FLAG_CONFIRMED_R = 0x80000000; | const EXCHGID4_FLAG_CONFIRMED_R = 0x80000000; | |||
struct state_protect_ops4 { | struct state_protect_ops4 { | |||
bitmap4 spo_must_enforce; | bitmap4 spo_must_enforce; | |||
bitmap4 spo_must_allow; | bitmap4 spo_must_allow; | |||
}; | }; | |||
struct ssv_sp_parms4 { | struct ssv_sp_parms4 { | |||
state_protect_ops4 ssp_ops; | state_protect_ops4 ssp_ops; | |||
sec_oid4 ssp_hash_algs<>; | sec_oid4 ssp_hash_algs<>; | |||
sec_oid4 ssp_encr_algs<>; | sec_oid4 ssp_encr_algs<>; | |||
uint32_t ssp_window; | uint32_t ssp_window; | |||
uint32_t ssp_num_gss_handles; | uint32_t ssp_num_gss_handles; | |||
}; | }; | |||
enum state_protect_how4 { | enum state_protect_how4 { | |||
SP4_NONE = 0, | SP4_NONE = 0, | |||
SP4_MACH_CRED = 1, | SP4_MACH_CRED = 1, | |||
SP4_SSV = 2 | SP4_SSV = 2 | |||
}; | }; | |||
skipping to change at line 35186 ¶ | skipping to change at line 35273 ¶ | |||
case SP4_MACH_CRED: | case SP4_MACH_CRED: | |||
state_protect_ops4 spa_mach_ops; | state_protect_ops4 spa_mach_ops; | |||
case SP4_SSV: | case SP4_SSV: | |||
ssv_sp_parms4 spa_ssv_parms; | ssv_sp_parms4 spa_ssv_parms; | |||
}; | }; | |||
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> | |||
</artwork> | ||||
</figure> | ||||
</t> | ||||
</section> | </section> | |||
<section title="RESULT" | <section anchor="EXID-res" toc="exclude" numbered="true"> | |||
anchor="EXID-res" | <name>RESULT</name> | |||
toc="exclude"> | <sourcecode type="xdr"><![CDATA[ | |||
<t> | ||||
<figure> | ||||
<artwork> | ||||
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) { | |||
case SP4_NONE: | case SP4_NONE: | |||
void; | void; | |||
case SP4_MACH_CRED: | case SP4_MACH_CRED: | |||
state_protect_ops4 spr_mach_ops; | state_protect_ops4 spr_mach_ops; | |||
case SP4_SSV: | case SP4_SSV: | |||
ssv_prot_info4 spr_ssv_info; | ssv_prot_info4 spr_ssv_info; | |||
}; | }; | |||
struct EXCHANGE_ID4resok { | struct EXCHANGE_ID4resok { | |||
clientid4 eir_clientid; | clientid4 eir_clientid; | |||
sequenceid4 eir_sequenceid; | sequenceid4 eir_sequenceid; | |||
uint32_t eir_flags; | uint32_t eir_flags; | |||
state_protect4_r eir_state_protect; | state_protect4_r eir_state_protect; | |||
server_owner4 eir_server_owner; | server_owner4 eir_server_owner; | |||
opaque eir_server_scope<NFS4_OPAQUE_LIMIT>; | opaque eir_server_scope<NFS4_OPAQUE_LIMIT>; | |||
nfs_impl_id4 eir_server_impl_id<1>; | nfs_impl_id4 eir_server_impl_id<1>; | |||
}; | }; | |||
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> | |||
</artwork> | ||||
</figure> | ||||
</t> | ||||
</section> | </section> | |||
<section title="DESCRIPTION" | <section anchor="OP_EXCHANGE_ID_DESCRIPTION" toc="exclude" numbered="tru | |||
anchor="OP_EXCHANGE_ID_DESCRIPTION" | e"> | |||
toc="exclude"> | <name>DESCRIPTION</name> | |||
<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, | |||
by other means (e.g. Transparent State Migration), the | when the client_owner4 has already been registered | |||
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 | |||
client ID returned. | client ID returned. | |||
</t> | </t> | |||
<t> | <t> | |||
In situations in which the registration of the | In situations in which the registration of the | |||
client_owner has not occurred previously, | client_owner has not occurred previously, | |||
the client ID must first be used, along with | the client ID must first be used, along with | |||
the returned eir_sequenceid, in creating an | the returned eir_sequenceid, in creating an | |||
associated session using | associated session using | |||
CREATE_SESSION. | CREATE_SESSION. | |||
</t> | </t> | |||
<t> | <t> | |||
If the flag EXCHGID4_FLAG_CONFIRMED_R is set in the | If the flag EXCHGID4_FLAG_CONFIRMED_R is set in the | |||
result, eir_flags, then it is an indication that the | result, eir_flags, then it is an indication that the | |||
registration of the client_owner has already occurred | registration of the client_owner has already occurred | |||
and that a further CREATE_SESSION is not needed to | and that a further CREATE_SESSION is not needed to | |||
confirm it. Of course, subsequent CREATE_SESSION | confirm it. Of course, subsequent CREATE_SESSION | |||
operations may | operations may | |||
be needed for other reasons. | be needed for other reasons. | |||
</t> | </t> | |||
<t> | <t> | |||
The value eir_sequenceid is used to establish an initial | The value eir_sequenceid is used to establish an initial | |||
sequence value associate with the client ID returned. In | sequence value associated with the client ID returned. In | |||
cases in which a CREATE_SESSION has already been done, | cases in which a CREATE_SESSION has already been done, | |||
there is no need for this value, since sequencing of | there is no need for this value, since sequencing of | |||
such request has already been established and the client | such request has already been established, and the client | |||
has no need for this value and will ignore it | has no need for this value and will ignore it. | |||
</t> | </t> | |||
<t> | <t> | |||
EXCHANGE_ID MAY be sent in a COMPOUND procedure that starts with | EXCHANGE_ID <bcp14>MAY</bcp14> be sent in a COMPOUND procedure that starts | |||
with | ||||
SEQUENCE. However, when a client communicates with a server | SEQUENCE. However, when a client communicates with a server | |||
for the first time, it will not have a session, so using | for the first time, it will not have a session, so using | |||
SEQUENCE will not be possible. | SEQUENCE will not be possible. | |||
If EXCHANGE_ID is sent without a preceding SEQUENCE, then it | If EXCHANGE_ID is sent without a preceding SEQUENCE, then it | |||
MUST be the only operation in the COMPOUND procedure's request. If | <bcp14>MUST</bcp14> be the only operation in the COMPOUND procedure's reque | |||
it is not, the server MUST return NFS4ERR_NOT_ONLY_OP. | st. If | |||
</t> | it is not, the server <bcp14>MUST</bcp14> return NFS4ERR_NOT_ONLY_OP. | |||
</t> | ||||
<t> | <t> | |||
The eia_clientowner field is composed of a co_verifier | The eia_clientowner field is composed of a co_verifier | |||
field and a co_ownerid string. As noted in | field and a co_ownerid string. As noted in | |||
<xref target="Client_Identifiers"/>, the co_ownerid | <xref target="Client_Identifiers" format="default"/>, the co_ownerid | |||
identifies the client, and the co_verifier specifies a particular | identifies the client, and the co_verifier specifies a particular | |||
incarnation of that client. An EXCHANGE_ID | incarnation of that client. An EXCHANGE_ID | |||
sent with a new incarnation of the client will | sent with a new incarnation of the client will | |||
lead to the server removing lock state of the old | lead to the server removing lock state of the old | |||
incarnation. On the other hand, an EXCHANGE_ID sent with the | incarnation. On the other hand, when an EXCHANGE_ID sent with the current | |||
current incarnation and co_ownerid will, when it does not result | incarnation and co_ownerid does not result in an unrelated error, | |||
in an unrelated error, potentially update an | it will potentially update an existing client ID's properties or | |||
existing client ID's properties, or simply | simply return information about the existing client_id. The latter | |||
return information about the existing client_id. That latter | ||||
would happen when this operation is done to the same server | would happen when this operation is done to the same server | |||
using different network addresses as part of creating trunked | using different network addresses as part of creating trunked | |||
connections. | connections. | |||
</t> | </t> | |||
<t> | <t> | |||
A server MUST NOT provide the same client ID to two different | A server <bcp14>MUST NOT</bcp14> provide the same client ID to two differe | |||
nt | ||||
incarnations of an eia_clientowner. | incarnations of an eia_clientowner. | |||
</t> | </t> | |||
<t> | <t> | |||
In addition to the client ID and sequence ID, the server | In addition to the client ID and sequence ID, the server | |||
returns a server owner (eir_server_owner) and | returns a server owner (eir_server_owner) and | |||
server scope (eir_server_scope). The former field is used | server scope (eir_server_scope). The former field is used | |||
in connection with | in connection with | |||
network trunking as described in <xref | network trunking as described in <xref target="Trunking" format="default"/> | |||
target="Trunking" />. The latter field is used to | . The latter field is used to | |||
allow clients to determine when client IDs sent by | allow clients to determine when client IDs sent by | |||
one server may be recognized by another in the event | one server may be recognized by another in the event | |||
of file system migration (see <xref | of file system migration (see <xref target="SEC11-EFF-lock" format="default | |||
target="SEC11-EFF-lock" /> of the current document). | "/> of the current document). | |||
</t> | </t> | |||
<t> | <t> | |||
The client ID returned by EXCHANGE_ID is only unique | The client ID returned by EXCHANGE_ID is only unique | |||
relative to the combination of eir_server_owner.so_major_id | relative to the combination of eir_server_owner.so_major_id | |||
and eir_server_scope. Thus, if two servers return the | and eir_server_scope. Thus, if two servers return the | |||
same client ID, the onus is on the client to | same client ID, the onus is on the client to | |||
distinguish the client IDs on the basis of eir_server_owner.so_major_id | distinguish the client IDs on the basis of eir_server_owner.so_major_id | |||
and eir_server_scope. In the event two different servers | and eir_server_scope. In the event two different servers | |||
claim matching server_owner.so_major_id and eir_server_scope, | claim matching server_owner.so_major_id and eir_server_scope, | |||
the client can use the verification techniques discussed | the client can use the verification techniques discussed | |||
in <xref target="PREP-trunk-verify" /> to determine if the servers | in <xref target="PREP-trunk-verify" format="default"/> to determine if the servers | |||
are distinct. If they are distinct, then the client | are distinct. If they are distinct, then the client | |||
will need to note the destination network addresses | will need to note the destination network addresses | |||
of the connections used with each server and use | of the connections used with each server and use | |||
the network address as the final discriminator. | the network address as the final discriminator. | |||
</t> | </t> | |||
<t> | <t> | |||
The server, as defined by the unique identity expressed | The server, as defined by the unique identity expressed | |||
in the so_major_id of the server owner and the server scope, | in the so_major_id of the server owner and the server scope, | |||
needs to track several properties of each client ID it | needs to track several properties of each client ID it | |||
hands out. The properties apply to the client ID and all | hands out. The properties apply to the client ID and all | |||
sessions associated with the client ID. | sessions associated with the client ID. | |||
The properties are derived from the | The properties are derived from the | |||
arguments and results of EXCHANGE_ID. | arguments and results of EXCHANGE_ID. | |||
The client ID properties include: | The client ID properties include: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
The capabilities expressed by the following bits, which | The capabilities expressed by the following bits, which | |||
come from the results of EXCHANGE_ID: | come from the results of EXCHANGE_ID: | |||
<list> | </t> | |||
<t>EXCHGID4_FLAG_SUPP_MOVED_REFER</t> | <ul spacing="normal"> | |||
<t>EXCHGID4_FLAG_SUPP_MOVED_MIGR </t> | <li>EXCHGID4_FLAG_SUPP_MOVED_REFER</li> | |||
<t>EXCHGID4_FLAG_BIND_PRINC_STATEID </t> | <li>EXCHGID4_FLAG_SUPP_MOVED_MIGR </li> | |||
<t>EXCHGID4_FLAG_USE_NON_PNFS </t> | <li>EXCHGID4_FLAG_BIND_PRINC_STATEID </li> | |||
<t>EXCHGID4_FLAG_USE_PNFS_MDS </t> | <li>EXCHGID4_FLAG_USE_NON_PNFS </li> | |||
<t>EXCHGID4_FLAG_USE_PNFS_DS </t> | <li>EXCHGID4_FLAG_USE_PNFS_MDS </li> | |||
</list> | <li>EXCHGID4_FLAG_USE_PNFS_DS </li> | |||
</ul> | ||||
<t> | ||||
These properties may be updated by subsequent | These properties may be updated by subsequent | |||
EXCHANGE_ID operations on confirmed client IDs though the server MAY | EXCHANGE_ID operations on confirmed client IDs though the server <bcp14> MAY</bcp14> | |||
refuse to change them. | refuse to change them. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
The state protection method used, one of SP4_NONE, | The state protection method used, one of SP4_NONE, | |||
SP4_MACH_CRED, or SP4_SSV, as set by the spa_how | SP4_MACH_CRED, or SP4_SSV, as set by the spa_how | |||
field of the arguments to EXCHANGE_ID. Once the | field of the arguments to EXCHANGE_ID. Once the | |||
client ID is confirmed, this property cannot be | client ID is confirmed, this property cannot be | |||
updated by subsequent EXCHANGE_ID operations. | updated by subsequent EXCHANGE_ID operations. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
For SP4_MACH_CRED or SP4_SSV state protection: | For SP4_MACH_CRED or SP4_SSV state protection: | |||
<list> | </t> | |||
<t> | <ul spacing="normal"> | |||
The list of operations (spo_must_enforce) that MUST use the specified | <li> | |||
The list of operations (spo_must_enforce) that <bcp14>MUST</bcp14> use t | ||||
he specified | ||||
state protection. This list comes | state protection. This list comes | |||
from the results of EXCHANGE_ID. | from the results of EXCHANGE_ID. | |||
</t> | </li> | |||
<t> | <li> | |||
The list of operations (spo_must_allow) that MAY use the specified | The list of operations (spo_must_allow) that <bcp14>MAY</bcp14> use the | |||
specified | ||||
state protection. This list comes | state protection. This list comes | |||
from the results of EXCHANGE_ID. | from the results of EXCHANGE_ID. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
Once the client ID is confirmed, these properties | Once the client ID is confirmed, these properties | |||
cannot be updated by subsequent EXCHANGE_ID | cannot be updated by subsequent EXCHANGE_ID | |||
requests. | requests. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
For SP4_SSV protection: | For SP4_SSV protection: | |||
<list> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <li> | |||
The OID of the hash algorithm. This property is | The OID of the hash algorithm. This property is | |||
represented by one of the algorithms in the | represented by one of the algorithms in the | |||
ssp_hash_algs field of the EXCHANGE_ID arguments. | ssp_hash_algs field of the EXCHANGE_ID arguments. | |||
Once the client ID is confirmed, this property | Once the client ID is confirmed, this property | |||
cannot be updated by subsequent EXCHANGE_ID | cannot be updated by subsequent EXCHANGE_ID | |||
requests. | requests. | |||
</t> | </li> | |||
<t> | <li> | |||
The OID of the encryption algorithm. This property | The OID of the encryption algorithm. This property | |||
is represented by one of the algorithms in the | is represented by one of the algorithms in the | |||
ssp_encr_algs field of the EXCHANGE_ID arguments. | ssp_encr_algs field of the EXCHANGE_ID arguments. | |||
Once the client ID is confirmed, this property | Once the client ID is confirmed, this property | |||
cannot be updated by subsequent EXCHANGE_ID | cannot be updated by subsequent EXCHANGE_ID | |||
requests. | requests. | |||
</t> | </li> | |||
<li> | ||||
<t> | <t> | |||
The length of the SSV. This property is | The length of the SSV. This property is | |||
represented by the spi_ssv_len field in the EXCHANGE_ID | represented by the spi_ssv_len field in the EXCHANGE_ID | |||
results. | results. | |||
Once the client ID is confirmed, | Once the client ID is confirmed, | |||
this property cannot be updated by | this property cannot be updated by | |||
subsequent EXCHANGE_ID operations. | subsequent EXCHANGE_ID operations. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
There are REQUIRED and RECOMMENDED relationships among the | There are <bcp14>REQUIRED</bcp14> and <bcp14>RECOMMENDED</bcp14> relation ships among the | |||
length of the key of the encryption algorithm ("key length"), the length of the | length of the key of the encryption algorithm ("key length"), the length of the | |||
output of hash algorithm ("hash length"), and the length of the SSV ("SSV length"). | output of hash algorithm ("hash length"), and the length of the SSV ("SSV length"). | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
key length MUST be <= hash length. This is because the keys used for | <li> | |||
key length <bcp14>MUST</bcp14> be <= hash length. This is because the | ||||
keys used for | ||||
the encryption algorithm are actually subkeys derived from the SSV, | the encryption algorithm are actually subkeys derived from the SSV, | |||
and the derivation is via the hash algorithm. The selection of an | and the derivation is via the hash algorithm. The selection of an | |||
encryption algorithm with a key length that exceeded the length of | encryption algorithm with a key length that exceeded the length of | |||
the output of the hash algorithm would require padding, and thus | the output of the hash algorithm would require padding, and thus | |||
weaken the use of the encryption algorithm. | weaken the use of the encryption algorithm. | |||
</t> | </li> | |||
<t> | <li> | |||
hash length SHOULD be <= SSV length. This is because the | hash length <bcp14>SHOULD</bcp14> be <= SSV length. This is because t | |||
he | ||||
SSV is a key used to derive subkeys via an HMAC, and | SSV is a key used to derive subkeys via an HMAC, and | |||
it is recommended that the key used as input to an HMAC be | it is recommended that the key used as input to an HMAC be | |||
at least as long as the length of the HMAC's hash algorithm's | at least as long as the length of the HMAC's hash algorithm's | |||
output (see Section 3 of <xref target="RFC2104"/>). | output (see <xref target="RFC2104" sectionFormat="of" section="3"/>). | |||
</t> | </li> | |||
<li> | ||||
<t> | key length <bcp14>SHOULD</bcp14> be <= SSV length. This is a transiti | |||
key length SHOULD be <= SSV length. This is a transitive result of th | ve result of the | |||
e | ||||
above two invariants. | above two invariants. | |||
</t> | </li> | |||
<li> | ||||
<t> | key length <bcp14>SHOULD</bcp14> be >= hash length / 2. This is becau | |||
key length SHOULD be >= hash length / 2. This is because the subkey | se the subkey | |||
derivation is via | derivation is via | |||
an HMAC and it is recommended that if the HMAC has to be truncated, | an HMAC and it is recommended that if the HMAC has to be truncated, | |||
it should not be truncated to less than half the hash length | it should not be truncated to less than half the hash length | |||
(see Section 4 of <xref target="RFC2104">RFC2104</xref>). | (see Section <xref target="RFC2104" sectionFormat="bare" section="4"/> | |||
</t> | of RFC 2104 <xref target="RFC2104" format="default"/>). | |||
</list> | </li> | |||
</t> | </ul> | |||
</li> | ||||
<t> | <li> | |||
Number of concurrent versions of the SSV the client | Number of concurrent versions of the SSV the client | |||
and server will support (see <xref target="ssv_mech"/>). | and server will support (see <xref target="ssv_mech" format="default"/>). | |||
This property is represented by spi_window | This property is represented by spi_window | |||
in the EXCHANGE_ID results. The property may be | in the EXCHANGE_ID results. The property may be | |||
updated by subsequent EXCHANGE_ID operations. | updated by subsequent EXCHANGE_ID operations. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
<t> | <li> | |||
The client's implementation ID as represented by | The client's implementation ID as represented by | |||
the eia_client_impl_id field of the arguments. | the eia_client_impl_id field of the arguments. | |||
The property may be updated by subsequent EXCHANGE_ID | The property may be updated by subsequent EXCHANGE_ID | |||
requests. | requests. | |||
</t> | </li> | |||
<t> | <li> | |||
The server's implementation ID as represented by | The server's implementation ID as represented by | |||
the eir_server_impl_id field of the reply. | the eir_server_impl_id field of the reply. | |||
The property may be updated by replies to subsequent EXCHANGE_ID | The property may be updated by replies to subsequent EXCHANGE_ID | |||
requests. | requests. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The eia_flags passed as part of the arguments and | The eia_flags passed as part of the arguments and | |||
the eir_flags results allow the client and server | the eir_flags results allow the client and server | |||
to inform each other of their capabilities as well | to inform each other of their capabilities as well | |||
as indicate how the client ID will be used. Whether | as indicate how the client ID will be used. Whether | |||
a bit is set or cleared on the arguments' flags | a bit is set or cleared on the arguments' flags | |||
does not force the server to set or clear the same | does not force the server to set or clear the same | |||
bit on the results' side. Bits not defined above | bit on the results' side. Bits not defined above | |||
cannot be set in the eia_flags field. If they | cannot be set in the eia_flags field. If they | |||
are, the server MUST reject the operation with | are, the server <bcp14>MUST</bcp14> reject the operation with | |||
NFS4ERR_INVAL. | NFS4ERR_INVAL. | |||
</t> | </t> | |||
<t> | <t> | |||
The EXCHGID4_FLAG_UPD_CONFIRMED_REC_A bit can only be set | The EXCHGID4_FLAG_UPD_CONFIRMED_REC_A bit can only be set | |||
in eia_flags; it is always off in eir_flags. | in eia_flags; it is always off in eir_flags. | |||
The EXCHGID4_FLAG_CONFIRMED_R bit can only be set in | The EXCHGID4_FLAG_CONFIRMED_R bit can only be set in | |||
eir_flags; it is always off in eia_flags. If the | eir_flags; it is always off in eia_flags. If the | |||
server recognizes the co_ownerid and co_verifier | server recognizes the co_ownerid and co_verifier | |||
as mapping to a confirmed client ID, it sets | as mapping to a confirmed client ID, it sets | |||
EXCHGID4_FLAG_CONFIRMED_R in eir_flags. | EXCHGID4_FLAG_CONFIRMED_R in eir_flags. | |||
The EXCHGID4_FLAG_CONFIRMED_R flag allows a client | The EXCHGID4_FLAG_CONFIRMED_R flag allows a client | |||
to tell if the client ID it is trying to create | to tell if the client ID it is trying to create | |||
already exists and is confirmed. | already exists and is confirmed. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set in eia_flags, | If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set in eia_flags, | |||
this means that the client is attempting to update properties | this means that the client is attempting to update properties | |||
of an existing confirmed client ID (if the client wants to | of an existing confirmed client ID (if the client wants to | |||
update properties of an unconfirmed client ID, it MUST NOT | update properties of an unconfirmed client ID, it <bcp14>MUST NOT</bcp14> | |||
set EXCHGID4_FLAG_UPD_CONFIRMED_REC_A). | set EXCHGID4_FLAG_UPD_CONFIRMED_REC_A). | |||
If so, it is | If so, it is | |||
RECOMMENDED that the client send the update EXCHANGE_ID | <bcp14>RECOMMENDED</bcp14> that the client send the update EXCHANGE_ID | |||
operation in the same COMPOUND as a SEQUENCE so that | operation in the same COMPOUND as a SEQUENCE so that | |||
the EXCHANGE_ID is executed exactly once. Whether | the EXCHANGE_ID is executed exactly once. Whether | |||
the client can update the properties of client ID | the client can update the properties of client ID | |||
depends on the state protection it selected when the | depends on the state protection it selected when the | |||
client ID was created, and the principal and security | client ID was created, and the principal and security | |||
flavor it used when sending the EXCHANGE_ID operation. | flavor it used when sending the EXCHANGE_ID operation. | |||
The situations described in items | The situations described in items | |||
<xref target="case_update" format="counter"/>, | <xref target="case_update" format="counter"/>, | |||
<xref target="case_update_noent" format="counter"/>, | <xref target="case_update_noent" format="counter"/>, | |||
<xref target="case_update_exist" format="counter"/>, | <xref target="case_update_exist" format="counter"/>, | |||
or | or | |||
<xref target="case_update_perm" format="counter"/> | <xref target="case_update_perm" format="counter"/> | |||
of the second numbered list of <xref | of the second numbered list of <xref target="OP_EXCHANGE_ID_IMPLEMENTATION | |||
target="OP_EXCHANGE_ID_IMPLEMENTATION" /> below will apply. | " format="default"/> below will apply. | |||
Note that if the operation succeeds | Note that if the operation succeeds | |||
and returns a client ID that is already | and returns a client ID that is already | |||
confirmed, the server MUST set the | confirmed, the server <bcp14>MUST</bcp14> set the | |||
EXCHGID4_FLAG_CONFIRMED_R bit in eir_flags. | EXCHGID4_FLAG_CONFIRMED_R bit in eir_flags. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not set in eia_flags, | If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not set in eia_flags, | |||
this means that the client is trying to establish a new | this means that the client is trying to establish a new | |||
client ID; it is | client ID; it is | |||
attempting to trunk data communication to | attempting to trunk data communication to | |||
the server (See <xref target="Trunking"/>); or it | the server (See <xref target="Trunking" format="default"/>); or it | |||
is attempting to update properties of an unconfirmed | is attempting to update properties of an unconfirmed | |||
client ID. The | client ID. The | |||
situations described in | situations described in | |||
items | items | |||
<xref target="case_new_owner_id" format="counter"/>, | <xref target="case_new_owner_id" format="counter"/>, | |||
<xref target="case_non_update" format="counter"/>, | <xref target="case_non_update" format="counter"/>, | |||
<xref target="case_client_collision" format="counter"/>, | <xref target="case_client_collision" format="counter"/>, | |||
<xref target="case_retry" format="counter"/>, or | <xref target="case_retry" format="counter"/>, or | |||
<xref target="case_client_restart" format="counter"/> | <xref target="case_client_restart" format="counter"/> | |||
of the second numbered list of <xref | of the second numbered list of <xref target="OP_EXCHANGE_ID_IMPLEMENTATION | |||
target="OP_EXCHANGE_ID_IMPLEMENTATION" /> below will apply. | " format="default"/> below will apply. | |||
Note that if the operation succeeds | Note that if the operation succeeds | |||
and returns a client ID that was previously | and returns a client ID that was previously | |||
confirmed, the server MUST set the | confirmed, the server <bcp14>MUST</bcp14> set the | |||
EXCHGID4_FLAG_CONFIRMED_R bit in eir_flags. | EXCHGID4_FLAG_CONFIRMED_R bit in eir_flags. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
When the EXCHGID4_FLAG_SUPP_MOVED_REFER flag bit | When the EXCHGID4_FLAG_SUPP_MOVED_REFER flag bit | |||
is set, the client indicates that it is capable | is set, the client indicates that it is capable | |||
of dealing with an NFS4ERR_MOVED error as part of | of dealing with an NFS4ERR_MOVED error as part of | |||
a referral sequence. When this bit is not set, it | a referral sequence. When this bit is not set, it | |||
is still legal for the server to perform a referral | is still legal for the server to perform a referral | |||
sequence. However, a server may use the fact that | sequence. However, a server may use the fact that | |||
the client is incapable of correctly responding | the client is incapable of correctly responding | |||
to a referral, by avoiding it for that particular | to a referral, by avoiding it for that particular | |||
client. It may, for instance, act as a proxy | client. It may, for instance, act as a proxy | |||
for that particular file system, at some cost in | for that particular file system, at some cost in | |||
performance, although it is not obligated to do so. | performance, although it is not obligated to do so. | |||
If the server will potentially perform a referral, it | If the server will potentially perform a referral, it | |||
MUST set EXCHGID4_FLAG_SUPP_MOVED_REFER in eir_flags. | <bcp14>MUST</bcp14> set EXCHGID4_FLAG_SUPP_MOVED_REFER in eir_flags. | |||
</t> | </t> | |||
<t> | <t> | |||
When the EXCHGID4_FLAG_SUPP_MOVED_MIGR is set, | When the EXCHGID4_FLAG_SUPP_MOVED_MIGR is set, | |||
the client indicates that it is capable of dealing | the client indicates that it is capable of dealing | |||
with an NFS4ERR_MOVED error as part of a file system | with an NFS4ERR_MOVED error as part of a file system | |||
migration sequence. When this bit is not set, it | migration sequence. When this bit is not set, it | |||
is still legal for the server to indicate that a | is still legal for the server to indicate that a | |||
file system has moved, when this in fact happens. | file system has moved, when this in fact happens. | |||
However, a server may use the fact that the client | However, a server may use the fact that the client | |||
is incapable of correctly responding to a migration | is incapable of correctly responding to a migration | |||
in its scheduling of file systems to migrate so as to | in its scheduling of file systems to migrate so as to | |||
avoid migration of file systems being actively used. | avoid migration of file systems being actively used. | |||
It may also hide actual migrations from clients | It may also hide actual migrations from clients | |||
unable to deal with them by acting as a proxy for a | unable to deal with them by acting as a proxy for a | |||
migrated file system for particular clients, at some | migrated file system for particular clients, at some | |||
cost in performance, although it is not obligated | cost in performance, although it is not obligated | |||
to do so. If the server will potentially perform a | to do so. If the server will potentially perform a | |||
migration, it MUST set EXCHGID4_FLAG_SUPP_MOVED_MIGR | migration, it <bcp14>MUST</bcp14> set EXCHGID4_FLAG_SUPP_MOVED_MIGR | |||
in eir_flags. | in eir_flags. | |||
</t> | </t> | |||
<t> | <t> | |||
When EXCHGID4_FLAG_BIND_PRINC_STATEID is set, the | When EXCHGID4_FLAG_BIND_PRINC_STATEID is set, the | |||
client indicates that it wants the server to bind the | client indicates that it wants the server to bind the | |||
stateid to the principal. This means that when a | stateid to the principal. This means that when a | |||
principal creates a stateid, it has to be the one to | principal creates a stateid, it has to be the one to | |||
use the stateid. If the server will perform binding, | use the stateid. If the server will perform binding, | |||
it will return EXCHGID4_FLAG_BIND_PRINC_STATEID. The | it will return EXCHGID4_FLAG_BIND_PRINC_STATEID. The | |||
server MAY return EXCHGID4_FLAG_BIND_PRINC_STATEID | server <bcp14>MAY</bcp14> return EXCHGID4_FLAG_BIND_PRINC_STATEID | |||
even if the client does not request it. If | even if the client does not request it. If | |||
an update to the client ID changes the value | an update to the client ID changes the value | |||
of EXCHGID4_FLAG_BIND_PRINC_STATEID's client | of EXCHGID4_FLAG_BIND_PRINC_STATEID's client | |||
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> | |||
<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"/> 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 MUST 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, | |||
the server might return different client IDs. Given | the server might return different client IDs. Given | |||
that different pNFS roles might have different client | that different pNFS roles might have different client | |||
IDs, the client may ask for different properties for | IDs, the client may ask for different properties for | |||
each role/client ID. | each role/client ID. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
The spa_how field of the eia_state_protect field | The spa_how field of the eia_state_protect field | |||
specifies how the client wants to protect its client, | specifies how the client wants to protect its client, | |||
locking, and session states from unauthorized changes | locking, and session states from unauthorized changes | |||
(<xref target="protect_state_change"/>): | (<xref target="protect_state_change" format="default"/>): | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
SP4_NONE. The client does not request the NFSv4.1 server | SP4_NONE. The client does not request the NFSv4.1 server | |||
to enforce state protection. The NFSv4.1 server MUST NOT | to enforce state protection. The NFSv4.1 server <bcp14>MUST NOT</bcp14> | |||
enforce state protection for the returned client ID. | enforce state protection for the returned client ID. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
SP4_MACH_CRED. If spa_how is SP4_MACH_CRED, then | SP4_MACH_CRED. If spa_how is SP4_MACH_CRED, then | |||
the client MUST send the EXCHANGE_ID operation with RPCSEC_GSS | the client <bcp14>MUST</bcp14> send the EXCHANGE_ID operation with RPCSEC_ GSS | |||
as the security flavor, and with a service of | as the security flavor, and with a service of | |||
RPC_GSS_SVC_INTEGRITY or RPC_GSS_SVC_PRIVACY. If SP4_MACH_CRED | RPC_GSS_SVC_INTEGRITY or RPC_GSS_SVC_PRIVACY. If SP4_MACH_CRED | |||
is specified, then the | is specified, then the | |||
client wants to use an RPCSEC_GSS-based machine | client wants to use an RPCSEC_GSS-based machine | |||
credential to protect its state. The server MUST note | credential to protect its state. The server <bcp14>MUST</bcp14> note | |||
the principal the EXCHANGE_ID operation was sent | the principal the EXCHANGE_ID operation was sent | |||
with, and the GSS mechanism used. These notes | with, and the GSS mechanism used. These notes | |||
collectively comprise the machine credential. | collectively comprise the machine credential. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
After the client ID is confirmed, as long as the lease associated with | After the client ID is confirmed, as long as the lease associated with | |||
the client ID is unexpired, a subsequent EXCHANGE_ID | the client ID is unexpired, a subsequent EXCHANGE_ID | |||
operation that uses the same eia_clientowner.co_owner | operation that uses the same eia_clientowner.co_owner | |||
as the first EXCHANGE_ID MUST also use the same | as the first EXCHANGE_ID <bcp14>MUST</bcp14> also use the same | |||
machine credential as the first EXCHANGE_ID. The | machine credential as the first EXCHANGE_ID. The | |||
server returns the same client ID for | server returns the same client ID for | |||
the subsequent EXCHANGE_ID as that returned from | the subsequent EXCHANGE_ID as that returned from | |||
the first EXCHANGE_ID. | the first EXCHANGE_ID. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
SP4_SSV. If spa_how is SP4_SSV, then | SP4_SSV. If spa_how is SP4_SSV, then | |||
the client MUST send the EXCHANGE_ID operation with RPCSEC_GSS | the client <bcp14>MUST</bcp14> send the EXCHANGE_ID operation with RPCSEC_ GSS | |||
as the security flavor, and with a service of | as the security flavor, and with a service of | |||
RPC_GSS_SVC_INTEGRITY or RPC_GSS_SVC_PRIVACY. | RPC_GSS_SVC_INTEGRITY or RPC_GSS_SVC_PRIVACY. | |||
If SP4_SSV is specified, then | If SP4_SSV is specified, then | |||
the client wants to use the SSV to protect its state. | the client wants to use the SSV to protect its state. | |||
The server records the credential used in the request | The server records the credential used in the request | |||
as the machine credential (as defined above) for | as the machine credential (as defined above) for | |||
the eia_clientowner.co_owner. | the eia_clientowner.co_owner. | |||
The CREATE_SESSION operation that | The CREATE_SESSION operation that | |||
confirms the client ID MUST use the same machine | confirms the client ID <bcp14>MUST</bcp14> use the same machine | |||
credential. | credential. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
When a client specifies SP4_MACH_CRED or SP4_SSV, | When a client specifies SP4_MACH_CRED or SP4_SSV, | |||
it also provides two lists of operations (each | it also provides two lists of operations (each | |||
expressed as a bitmap). The first list | expressed as a bitmap). The first list | |||
is spo_must_enforce and consists of those operations | is spo_must_enforce and consists of those operations | |||
the client MUST send (subject to the server confirming the | the client <bcp14>MUST</bcp14> send (subject to the server confirming the | |||
list of operations in the result of EXCHANGE_ID) with the | list of operations in the result of EXCHANGE_ID) with the | |||
machine credential (if SP4_MACH_CRED protection is | machine credential (if SP4_MACH_CRED protection is | |||
specified) or the SSV-based credential (if SP4_SSV | specified) or the SSV-based credential (if SP4_SSV | |||
protection is used). The client MUST send the | protection is used). The client <bcp14>MUST</bcp14> send the | |||
operations with RPCSEC_GSS credentials that specify | operations with RPCSEC_GSS credentials that specify | |||
the RPC_GSS_SVC_INTEGRITY or RPC_GSS_SVC_PRIVACY | the RPC_GSS_SVC_INTEGRITY or RPC_GSS_SVC_PRIVACY | |||
security service. Typically, the first list of | security service. Typically, the first list of | |||
operations includes EXCHANGE_ID, CREATE_SESSION, | operations includes EXCHANGE_ID, CREATE_SESSION, | |||
DELEGPURGE, DESTROY_SESSION, BIND_CONN_TO_SESSION, | DELEGPURGE, DESTROY_SESSION, BIND_CONN_TO_SESSION, | |||
and DESTROY_CLIENTID. The client SHOULD NOT specify | and DESTROY_CLIENTID. The client <bcp14>SHOULD NOT</bcp14> specify | |||
in this list any operations that require a filehandle | in this list any operations that require a filehandle | |||
because the server's access policies MAY conflict with | because the server's access policies <bcp14>MAY</bcp14> conflict with | |||
the client's choice, and thus the client would then be | the client's choice, and thus the client would then be | |||
unable to access a subset of the server's namespace. | unable to access a subset of the server's namespace. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that if SP4_SSV protection is specified, and | Note that if SP4_SSV protection is specified, and | |||
the client indicates that CREATE_SESSION must be | the client indicates that CREATE_SESSION must be | |||
protected with SP4_SSV, because the SSV cannot exist | protected with SP4_SSV, because the SSV cannot exist | |||
without a confirmed client ID, the first CREATE_SESSION | without a confirmed client ID, the first CREATE_SESSION | |||
MUST instead be sent using the machine credential, | <bcp14>MUST</bcp14> instead be sent using the machine credential, | |||
and the server MUST accept the machine credential. | and the server <bcp14>MUST</bcp14> accept the machine credential. | |||
</t> | </t> | |||
<t> | <t> | |||
There is a corresponding result, also called spo_must_enforce, | There is a corresponding result, also called spo_must_enforce, | |||
of the operations for which the server will require SP4_MACH_CRED or | of the operations for which the server will require SP4_MACH_CRED or | |||
SP4_SSV protection. Normally, the server's result | SP4_SSV protection. Normally, the server's result | |||
equals the client's argument, but the result MAY be different. | equals the client's argument, but the result <bcp14>MAY</bcp14> be differen t. | |||
If the client requests one or more operations in | If the client requests one or more operations in | |||
the set { EXCHANGE_ID, CREATE_SESSION, | the set { EXCHANGE_ID, CREATE_SESSION, | |||
DELEGPURGE, DESTROY_SESSION, BIND_CONN_TO_SESSION, | DELEGPURGE, DESTROY_SESSION, BIND_CONN_TO_SESSION, | |||
DESTROY_CLIENTID }, then the result spo_must_enforce | DESTROY_CLIENTID }, then the result spo_must_enforce | |||
MUST include the operations the client requested from that set. | <bcp14>MUST</bcp14> include the operations the client requested from that s et. | |||
</t> | </t> | |||
<t> | <t> | |||
If spo_must_enforce in the results has BIND_CONN_TO_SESSION | If spo_must_enforce in the results has BIND_CONN_TO_SESSION | |||
set, then connection binding enforcement is enabled, and | set, then connection binding enforcement is enabled, and | |||
the client MUST use the machine (if SP4_MACH_CRED protection is used) | the client <bcp14>MUST</bcp14> use the machine (if SP4_MACH_CRED protection is used) | |||
or SSV (if SP4_SSV protection is used) credential on calls | or SSV (if SP4_SSV protection is used) credential on calls | |||
to BIND_CONN_TO_SESSION. | to BIND_CONN_TO_SESSION. | |||
</t> | </t> | |||
<t> | <t> | |||
The second list is spo_must_allow and consists of those | The second list is spo_must_allow and consists of those | |||
operations | operations | |||
the client wants to have the option of sending with the machine credential or | the client wants to have the option of sending with the machine credential or | |||
the SSV-based credential, even if the object the | the SSV-based credential, even if the object the | |||
operations are performed on is not owned by the | operations are performed on is not owned by the | |||
machine or SSV credential. | machine or SSV credential. | |||
</t> | </t> | |||
<t> | <t> | |||
The corresponding result, also called | The corresponding result, also called | |||
spo_must_allow, consists of the operations the server | spo_must_allow, consists of the operations the server | |||
will allow the client to use SP4_SSV or SP4_MACH_CRED | will allow the client to use SP4_SSV or SP4_MACH_CRED | |||
credentials with. | credentials with. | |||
Normally, the server's result | Normally, the server's result | |||
equals the client's argument, but the result MAY be different. | equals the client's argument, but the result <bcp14>MAY</bcp14> be differen t. | |||
</t> | </t> | |||
<t> | <t> | |||
The purpose of spo_must_allow is to allow clients to | The purpose of spo_must_allow is to allow clients to | |||
solve the following conundrum. Suppose the client ID | solve the following conundrum. Suppose the client ID | |||
is confirmed with EXCHGID4_FLAG_BIND_PRINC_STATEID, | is confirmed with EXCHGID4_FLAG_BIND_PRINC_STATEID, | |||
and it calls OPEN with the RPCSEC_GSS credentials of | and it calls OPEN with the RPCSEC_GSS credentials of | |||
a normal user. Now suppose the user's credentials expire, | a normal user. Now suppose the user's credentials expire, | |||
and cannot be renewed (e.g., a Kerberos ticket granting ticket | and cannot be renewed (e.g., a Kerberos ticket granting ticket | |||
expires, and the user has logged off and will not be | expires, and the user has logged off and will not be | |||
acquiring a new ticket granting ticket). The client will be | acquiring a new ticket granting ticket). The client will be | |||
unable to send CLOSE without the user's credentials, which is to | unable to send CLOSE without the user's credentials, which is to | |||
say the client has to either leave the state on the server | say the client has to either leave the state on the server | |||
or re-send EXCHANGE_ID with a new verifier to | or re-send EXCHANGE_ID with a new verifier to | |||
clear all state, that is, unless the client includes | clear all state, that is, unless the client includes | |||
CLOSE on the list of operations in spo_must_allow and the | CLOSE on the list of operations in spo_must_allow and the | |||
server agrees. | server agrees. | |||
</t> | </t> | |||
<t> | <t> | |||
The SP4_SSV protection parameters also have: | The SP4_SSV protection parameters also have: | |||
<list style="hanging"> | </t> | |||
<dl newline="true" spacing="normal"> | ||||
<t hangText="ssp_hash_algs:" /> | <dt>ssp_hash_algs:</dt> | |||
<t> | <dd><t> | |||
This is the set of algorithms the client supports | This is the set of algorithms the client supports | |||
for the purpose of computing the digests needed for | for the purpose of computing the digests needed for | |||
the internal SSV GSS mechanism and for the SET_SSV | the internal SSV GSS mechanism and for the SET_SSV | |||
operation. Each algorithm is specified as an object | operation. Each algorithm is specified as an object | |||
identifier (OID). The REQUIRED algorithms for a | identifier (OID). The <bcp14>REQUIRED</bcp14> algorithms for a | |||
server are id-sha1, id-sha224, id-sha256, id-sha384, | server are id-sha1, id-sha224, id-sha256, id-sha384, | |||
and id-sha512 <xref target="RFC4055"/>. | and id-sha512 <xref target="RFC4055" format="default"/>.</t> | |||
</t> | <t> | |||
<t> | Due to known weaknesses in id-sha1, it is <bcp14>RECOMMENDED</bcp14> | |||
Due to known weaknesses in id-sha1, it is RECOMMENDED | ||||
that the client specify at least one | that the client specify at least one | |||
algorithm within ssp_hash_algs other than id-sha1. | algorithm within ssp_hash_algs other than id-sha1.</t> | |||
</t> | <t> | |||
<t> | ||||
The algorithm the server selects among the | The algorithm the server selects among the | |||
set is indicated in spi_hash_alg, a field of | set is indicated in spi_hash_alg, a field of | |||
spr_ssv_prot_info. The field spi_hash_alg is an | spr_ssv_prot_info. The field spi_hash_alg is an | |||
index into the array ssp_hash_algs. Because of | index into the array ssp_hash_algs. Because of | |||
known the weaknesses in id-sha1, it is RECOMMENDED that | known the weaknesses in id-sha1, it is <bcp14>RECOMMENDED</bcp14> that | |||
it not be selected by the server as long as ssp_hash_algs | it not be selected by the server as long as ssp_hash_algs | |||
contains any other supported algorithm. | contains any other supported algorithm.</t> | |||
</t> | <t> | |||
<t> | ||||
If the server | If the server | |||
does not support any of the offered algorithms, | does not support any of the offered algorithms, | |||
it returns NFS4ERR_HASH_ALG_UNSUPP. | it returns NFS4ERR_HASH_ALG_UNSUPP. | |||
If ssp_hash_algs is empty, the server <bcp14>MUST</bcp14> return | ||||
If ssp_hash_algs is empty, the server MUST return NFS4ERR_INVAL. | NFS4ERR_INVAL. </t> | |||
</dd> | ||||
</t> | <dt>ssp_encr_algs:</dt> | |||
<t hangText="ssp_encr_algs:" /> | <dd> | |||
<t> | ||||
This is the set of algorithms the client supports for the | This is the set of algorithms the client supports for the | |||
purpose of providing privacy protection for the internal | purpose of providing privacy protection for the internal | |||
SSV GSS mechanism. Each algorithm is | SSV GSS mechanism. Each algorithm is | |||
specified as an OID. | specified as an OID. | |||
The REQUIRED algorithm for a server is id-aes256-CBC. | The <bcp14>REQUIRED</bcp14> algorithm for a server is id-aes256-CBC. | |||
The RECOMMENDED algorithms are id-aes192-CBC and id-aes128-CBC | The <bcp14>RECOMMENDED</bcp14> algorithms are id-aes192-CBC and id-aes128 | |||
<xref target="CSOR_AES" />. The selected algorithm is | -CBC | |||
<xref target="CSOR_AES" format="default"/>. The selected algorithm is | ||||
returned in spi_encr_alg, an index into ssp_encr_algs. | returned in spi_encr_alg, an index into ssp_encr_algs. | |||
If the server | If the server | |||
does not support any of the offered algorithms, | does not support any of the offered algorithms, | |||
it returns NFS4ERR_ENCR_ALG_UNSUPP. | it returns NFS4ERR_ENCR_ALG_UNSUPP. | |||
If ssp_encr_algs is empty, the server MUST return NFS4ERR_INVAL. | If ssp_encr_algs is empty, the server <bcp14>MUST</bcp14> return NFS4ERR_ INVAL. | |||
Note that due to previously stated requirements and recommendations | Note that due to previously stated requirements and recommendations | |||
on the relationships between key length and hash length, some | on the relationships between key length and hash length, some | |||
combinations of RECOMMENDED and REQUIRED encryption algorithm and | combinations of <bcp14>RECOMMENDED</bcp14> and <bcp14>REQUIRED</bcp14> en | |||
hash algorithm either SHOULD NOT or MUST NOT be used. | cryption algorithm and | |||
<xref target="algtbl"/> summarizes the illegal and discouraged | hash algorithm either <bcp14>SHOULD NOT</bcp14> or <bcp14>MUST NOT</bcp14 | |||
> be used. | ||||
<xref target="algtbl" format="default"/> summarizes the illegal and disco | ||||
uraged | ||||
combinations. | combinations. | |||
</dd> | ||||
</t> | <dt>ssp_window:</dt> | |||
<t hangText="ssp_window:" /> | <dd> | |||
<t> | ||||
This is the number of SSV versions the client wants | This is the number of SSV versions the client wants | |||
the server to maintain (i.e., each successful call to SET_SSV | the server to maintain (i.e., each successful call to SET_SSV | |||
produces a new version of the SSV). If ssp_window is zero, the | produces a new version of the SSV). If ssp_window is zero, the | |||
server MUST return NFS4ERR_INVAL. The server responds | server <bcp14>MUST</bcp14> return NFS4ERR_INVAL. The server responds | |||
with spi_window, which MUST NOT exceed ssp_window and MUST | with spi_window, which <bcp14>MUST NOT</bcp14> exceed ssp_window and <bcp | |||
14>MUST</bcp14> | ||||
be at least one. | be at least one. | |||
Any requests on the backchannel or fore channel that | Any requests on the backchannel or fore channel that | |||
are using a version of the SSV that is outside the window will fail with | are using a version of the SSV that is outside the window will fail with | |||
an ONC RPC authentication error, and the requester | an ONC RPC authentication error, and the requester | |||
will have to retry them with the same slot ID and | will have to retry them with the same slot ID and | |||
sequence ID. | sequence ID. | |||
</t> | </dd> | |||
<dt>ssp_num_gss_handles:</dt> | ||||
<t hangText="ssp_num_gss_handles:" /> | <dd> | |||
<t> | <t> | |||
This is the number of RPCSEC_GSS handles the | This is the number of RPCSEC_GSS handles the | |||
server should create that are based on the GSS | server should create that are based on the GSS | |||
SSV mechanism (see | SSV mechanism (see | |||
<xref target="ssv_mech" />). | <xref target="ssv_mech" format="default"/>). | |||
It is not the total number of RPCSEC_GSS handles for | It is not the total number of RPCSEC_GSS handles for | |||
the client ID. Indeed, subsequent calls to EXCHANGE_ID | the client ID. Indeed, subsequent calls to EXCHANGE_ID | |||
will add RPCSEC_GSS handles. | will add RPCSEC_GSS handles. | |||
The server responds with a list of handles in | The server responds with a list of handles in | |||
spi_handles. If the client asks for at least | spi_handles. If the client asks for at least | |||
one handle and the server cannot create it, | one handle and the server cannot create it, | |||
the server MUST return an error. The handles in | the server <bcp14>MUST</bcp14> return an error. The handles in | |||
spi_handles are not available for use until the | spi_handles are not available for use until the | |||
client ID is confirmed, which could be immediately | client ID is confirmed, which could be immediately | |||
if EXCHANGE_ID returns EXCHGID4_FLAG_CONFIRMED_R, | if EXCHANGE_ID returns EXCHGID4_FLAG_CONFIRMED_R, | |||
or upon successful confirmation from CREATE_SESSION. | or upon successful confirmation from CREATE_SESSION. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
While a client ID can span all the connections | While a client ID can span all the connections | |||
that are connected to a server sharing the same | that are connected to a server sharing the same | |||
eir_server_owner.so_major_id, the RPCSEC_GSS | eir_server_owner.so_major_id, the RPCSEC_GSS | |||
handles returned in spi_handles can only be used | handles returned in spi_handles can only be used | |||
on connections connected to a server that returns | on connections connected to a server that returns | |||
the same the eir_server_owner.so_major_id and | the same the eir_server_owner.so_major_id and | |||
eir_server_owner.so_minor_id on each connection. | eir_server_owner.so_minor_id on each connection. | |||
It is permissible for the client to set | It is permissible for the client to set | |||
ssp_num_gss_handles to zero; the client can | ssp_num_gss_handles to zero; the client can | |||
create more handles with another EXCHANGE_ID call. | create more handles with another EXCHANGE_ID call. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
Because each SSV RPCSEC_GSS handle shares a common SSV GSS context, | Because each SSV RPCSEC_GSS handle shares a common SSV GSS context, | |||
there are security considerations specific to this situation | there are security considerations specific to this situation | |||
discussed in <xref target="rpcsec_ssv_consider"/>. | discussed in <xref target="rpcsec_ssv_consider" format="default"/>. | |||
<vspace blankLines='1' /> | </t> | |||
The seq_window (see Section 5.2.3.1 of RFC2203 <xref target="RFC2203"/>) | <t> | |||
The seq_window (see Section <xref target="RFC2203" sectionFormat="bare" s | ||||
ection="5.2.3.1"/> of RFC 2203 | ||||
<xref target="RFC2203" format="default"/>) | ||||
of each RPCSEC_GSS handle in spi_handle | of each RPCSEC_GSS handle in spi_handle | |||
MUST be the same as the seq_window of | <bcp14>MUST</bcp14> be the same as the seq_window of | |||
the RPCSEC_GSS handle used for the credential of the RPC request | the RPCSEC_GSS handle used for the credential of the RPC request | |||
that the EXCHANGE_ID operation was sent as a part of. | of which the EXCHANGE_ID operation was sent as a part. | |||
</t> | ||||
</t> | </dd> | |||
</dl> | ||||
</list> | <table anchor="algtbl" align="center"> | |||
<thead> | ||||
</t> | <tr> | |||
<texttable anchor='algtbl'> | <th align="left">Encryption Algorithm</th> | |||
<ttcol align='left'>Encryption Algorithm</ttcol> | <th align="left"><bcp14>MUST NOT</bcp14> be combined with</th> | |||
<ttcol align='left'>MUST NOT be combined with</ttcol> | <th align="left"><bcp14>SHOULD NOT</bcp14> be combined with</th> | |||
<ttcol align='left'>SHOULD NOT be combined with</ttcol> | </tr> | |||
<c>id-aes128-CBC</c> <c></c> <c>id-sha384, id-sha512</c> | </thead> | |||
<c>id-aes192-CBC</c> <c>id-sha1</c> <c>id-sha512</c> | <tbody> | |||
<c>id-aes256-CBC</c> <c>id-sha1, id-sha224</c> <c></c> | <tr> | |||
</texttable> | <td align="left">id-aes128-CBC</td> | |||
<td align="left"/> | ||||
<t> | <td align="left">id-sha384, id-sha512</td> | |||
</tr> | ||||
<tr> | ||||
<td align="left">id-aes192-CBC</td> | ||||
<td align="left">id-sha1</td> | ||||
<td align="left">id-sha512</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">id-aes256-CBC</td> | ||||
<td align="left">id-sha1, id-sha224</td> | ||||
<td align="left"/> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
<t> | ||||
The arguments include an array of up to one | The arguments include an array of up to one | |||
element in length called eia_client_impl_id. If | element in length called eia_client_impl_id. If | |||
eia_client_impl_id is present, it contains the | eia_client_impl_id is present, it contains the | |||
information identifying the implementation of the | information identifying the implementation of the | |||
client. Similarly, the results include an array of up | client. Similarly, the results include an array of up | |||
to one element in length called eir_server_impl_id | to one element in length called eir_server_impl_id | |||
that identifies the implementation of the server. | that identifies the implementation of the server. | |||
Servers MUST accept a zero-length eia_client_impl_id | Servers <bcp14>MUST</bcp14> accept a zero-length eia_client_impl_id | |||
array, and clients MUST accept a zero-length | array, and clients <bcp14>MUST</bcp14> accept a zero-length | |||
eir_server_impl_id array. | eir_server_impl_id array. | |||
</t> | </t> | |||
<t> | <t> | |||
A possible use for implementation identifiers | A possible use for implementation identifiers | |||
would be in diagnostic software that extracts | would be in diagnostic software that extracts | |||
this information in an attempt to identify | this information in an attempt to identify | |||
interoperability problems, performance workload | interoperability problems, performance workload | |||
behaviors, or general usage statistics. Since the | behaviors, or general usage statistics. Since the | |||
intent of having access to this information is for | intent of having access to this information is for | |||
planning or general diagnosis only, the client and | planning or general diagnosis only, the client and | |||
server MUST NOT interpret this implementation | server <bcp14>MUST NOT</bcp14> interpret this implementation | |||
identity information in a way that affects | identity information in a way that affects | |||
how the implementation interacts with | how the implementation interacts with | |||
its peer. The client and server are not | its peer. The client and server are not | |||
allowed to depend on the peer's manifesting a particular | allowed to depend on the peer's manifesting a particular | |||
allowed behavior based on an implementation identifier | allowed behavior based on an implementation identifier | |||
but are required to interoperate as specified elsewhere | but are required to interoperate as specified elsewhere | |||
in the protocol specification. | in the protocol specification. | |||
</t> | </t> | |||
<t> | <t> | |||
Because it is possible that some implementations might | Because it is possible that some implementations might | |||
violate the protocol specification and interpret | violate the protocol specification and interpret | |||
the identity information, implementations MUST | the identity information, implementations <bcp14>MUST</bcp14> | |||
provide facilities to allow the NFSv4 client and server | provide facilities to allow the NFSv4 client and server | |||
be configured to | to be configured to set the contents of the nfs_impl_id structures sent | |||
set the contents of the nfs_impl_id structures sent | ||||
to any specified value. | to any specified value. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section anchor="OP_EXCHANGE_ID_IMPLEMENTATION" toc="exclude" numbered=" | |||
<section title="IMPLEMENTATION" | true"> | |||
anchor="OP_EXCHANGE_ID_IMPLEMENTATION" | <name>IMPLEMENTATION</name> | |||
toc="exclude"> | <t> | |||
<t> | ||||
A server's client record is a 5-tuple: | A server's client record is a 5-tuple: | |||
</t> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<list style="numbers"> | <li> | |||
<t>co_ownerid | <t>co_ownerid: | |||
<list style="empty"> | </t> | |||
<t>The client identifier string, from the eia_clientowner | <t> | |||
The client identifier string, from the eia_clientowner | ||||
structure of the EXCHANGE_ID4args structure.</t> | structure of the EXCHANGE_ID4args structure.</t> | |||
</list></t> | </li> | |||
<li> | ||||
<t>co_verifier: | <t>co_verifier: | |||
<list style="empty"> | </t> | |||
<t>A client-specific value used to indicate incarnations (where a clien | <t>A client-specific value used to indicate incarnations (where | |||
t restart represents a new incarnation), from the | a client restart represents a new incarnation), from the | |||
eia_clientowner structure of the EXCHANGE_ID4args | eia_clientowner structure of the EXCHANGE_ID4args | |||
structure.</t> | structure.</t> | |||
</list></t> | </li> | |||
<li> | ||||
<t>principal: | <t>principal: | |||
<list style="empty"> | </t> | |||
<t> | <t> | |||
The principal that was defined in the RPC header's credential | The principal that was defined in the RPC header's credential | |||
and/or verifier at the time the client record was | and/or verifier at the time the client record was | |||
established. | established. | |||
</t> | </t> | |||
</list></t> | </li> | |||
<li> | ||||
<t>client ID: | <t>client ID: | |||
<list style="empty"> | </t> | |||
<t>The shorthand client identifier, generated by the server and | <t>The shorthand client identifier, generated by the server and | |||
returned via the eir_clientid field in the EXCHANGE_ID4resok | returned via the eir_clientid field in the EXCHANGE_ID4resok | |||
structure.</t> | structure.</t> | |||
</list></t> | </li> | |||
<li> | ||||
<t>confirmed: | <t>confirmed: | |||
<list style="empty"> | </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 SHOULD be removed.</t> | period <bcp14>SHOULD</bcp14> be removed.</t> | |||
</list></t> | </li> | |||
</ol> | ||||
</list> | ||||
</t> | ||||
<!-- 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. | |||
<list style="hanging"> | </t> | |||
<t hangText="ownerid_arg:"/> | <dl newline="true" spacing="normal"> | |||
<t> | <dt>ownerid_arg:</dt> | |||
<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. | |||
</t> | </dd> | |||
<t hangText="verifier_arg:"/> | <dt>verifier_arg:</dt> | |||
<t> | <dd> | |||
The value of the eia_clientowner.co_verifier subfield of the | The value of the eia_clientowner.co_verifier subfield of the | |||
EXCHANGE_ID4args structure of the current request. | EXCHANGE_ID4args structure of the current request. | |||
</t> | </dd> | |||
<t hangText="old_verifier_arg:"/> | <dt>old_verifier_arg:</dt> | |||
<t> | <dd> | |||
A value of the eia_clientowner.co_verifier field of a client record | A value of the eia_clientowner.co_verifier field of a client record | |||
received in a previous request; this is distinct from | received in a previous request; this is distinct from | |||
verifier_arg. | verifier_arg. | |||
</t> | </dd> | |||
<t hangText="principal_arg:"/> | <dt>principal_arg:</dt> | |||
<t> | <dd> | |||
The value of the RPCSEC_GSS principal for the current request. | The value of the RPCSEC_GSS principal for the current request. | |||
</t> | </dd> | |||
<t hangText="old_principal_arg:"/> | <dt>old_principal_arg:</dt> | |||
<t> | <dd> | |||
A value of the principal of a client record as defined by the | A value of the principal of a client record as defined by the | |||
RPC header's credential or verifier of a previous request. | RPC header's credential or verifier of a previous request. | |||
This is distinct from principal_arg. | This is distinct from principal_arg. | |||
</dd> | ||||
</t> | <dt>clientid_ret:</dt> | |||
<t hangText="clientid_ret:"/> | <dd> | |||
<t> | ||||
The value of the eir_clientid field the server will return in the | The value of the eir_clientid field the server will return in the | |||
EXCHANGE_ID4resok structure for the current request. | EXCHANGE_ID4resok structure for the current request. | |||
</t> | </dd> | |||
<t hangText="old_clientid_ret:"/> | <dt>old_clientid_ret:</dt> | |||
<t> | <dd> | |||
The value of the eir_clientid field the server returned in the | The value of the eir_clientid field the server returned in the | |||
EXCHANGE_ID4resok structure for a previous request. This | EXCHANGE_ID4resok structure for a previous request. This | |||
is distinct from clientid_ret. | is distinct from clientid_ret. | |||
</t> | </dd> | |||
<t hangText="confirmed:"/> | <dt>confirmed:</dt> | |||
<t> | <dd> | |||
The client ID has been confirmed. | The client ID has been confirmed. | |||
</t> | </dd> | |||
<t hangText="unconfirmed:"/> | <dt>unconfirmed:</dt> | |||
<t> | <dd> | |||
The client ID has not been confirmed. | The client ID has not been confirmed. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | <t> | |||
<t> | ||||
Since EXCHANGE_ID is a non-idempotent operation, we must | Since EXCHANGE_ID is a non-idempotent operation, we must | |||
consider the possibility that retries occur as a result of a | consider the possibility that retries occur as a result of a | |||
client restart, network partition, malfunctioning router, etc. | client restart, network partition, malfunctioning router, etc. | |||
Retries are identified by the value of the eia_clientowner field of | Retries are identified by the value of the eia_clientowner field of | |||
EXCHANGE_ID4args, and the method for dealing with them is | EXCHANGE_ID4args, and the method for dealing with them is | |||
outlined in the scenarios below. | outlined in the scenarios below. | |||
</t> | </t> | |||
<t> | <t> | |||
The scenarios are described in terms of the | The scenarios are described in terms of the | |||
client record(s) a server has for a given | client record(s) a server has for a given | |||
co_ownerid. Note that if the client ID | co_ownerid. Note that if the client ID | |||
was created specifying SP4_SSV state protection and | was created specifying SP4_SSV state protection and | |||
EXCHANGE_ID as the one of the operations in spo_must_allow, | EXCHANGE_ID as the one of the operations in spo_must_allow, | |||
then the server MUST authorize EXCHANGE_IDs with the SSV | then the server <bcp14>MUST</bcp14> authorize EXCHANGE_IDs with the SSV | |||
principal in addition to the principal that created the | principal in addition to the principal that created the | |||
client ID. | client ID. | |||
</t> | </t> | |||
<t anchor="case_list"> | ||||
<list style="numbers"> | <ol spacing="normal" type="1"> | |||
<t anchor="case_new_owner_id">New Owner ID | <li anchor="case_new_owner_id"> | |||
<list style="empty"> | <t>New Owner ID | |||
<t> | </t> | |||
<t> | ||||
If the server has no client records | If the server has no client records | |||
with eia_clientowner.co_ownerid matching | with eia_clientowner.co_ownerid matching | |||
ownerid_arg, and EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not | ownerid_arg, and EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not | |||
set in the EXCHANGE_ID, then a new shorthand | set in the EXCHANGE_ID, then a new shorthand | |||
client ID (let us call it clientid_ret) | client ID (let us call it clientid_ret) | |||
is generated, and the following unconfirmed | is generated, and the following unconfirmed | |||
record is added to the server's state. | record is added to the server's state. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
{ ownerid_arg, verifier_arg, principal_arg, clientid_ret, unconfirmed } | { ownerid_arg, verifier_arg, principal_arg, clientid_ret, unconfirmed } | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
Subsequently, the server returns clientid_ret. | Subsequently, the server returns clientid_ret. | |||
</t> | ||||
</li> | ||||
<vspace blankLines='1' /> | <li anchor="case_non_update"> | |||
<t>Non-Update on Existing Client ID</t> | ||||
</t> | <t> | |||
</list> | ||||
<vspace blankLines='1' /> | ||||
</t> | ||||
<t anchor="case_non_update">Non-Update on Existing Client ID | ||||
<list style="empty"> | ||||
<t> | ||||
If the server has the following confirmed record, and | If the server has the following confirmed record, and | |||
the request does not have | the request does not have | |||
EXCHGID4_FLAG_UPD_CONFIRMED_REC_A set, | EXCHGID4_FLAG_UPD_CONFIRMED_REC_A set, | |||
then the request is the result of a retried request due to a | then the request is the result of a retried request due to a | |||
faulty router or lost connection, or | faulty router or lost connection, or | |||
the client is trying to determine if it can perform | the client is trying to determine if it can perform | |||
trunking. | trunking. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
{ ownerid_arg, verifier_arg, principal_arg, clientid_ret, confirmed } | { ownerid_arg, verifier_arg, principal_arg, clientid_ret, confirmed } | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
Since the record has been confirmed, the client | Since the record has been confirmed, the client | |||
must have received the server's reply from | must have received the server's reply from | |||
the initial EXCHANGE_ID request. Since the | the initial EXCHANGE_ID request. Since the | |||
server has a confirmed record, and since | server has a confirmed record, and since | |||
EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not set, with the | EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not set, with the | |||
possible exception of eir_server_owner.so_minor_id, the | possible exception of eir_server_owner.so_minor_id, the | |||
server returns the same result it did when | server returns the same result it did when | |||
the client ID's properties were last updated | the client ID's properties were last updated | |||
(or if never updated, the result when the | (or if never updated, the result when the | |||
client ID was created). The confirmed record | client ID was created). The confirmed record | |||
is unchanged. | is unchanged. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | ||||
<t anchor="case_client_collision">Client Collision | <li anchor="case_client_collision"> | |||
<list style="empty"> | <t>Client Collision | |||
<t> | </t> | |||
<t> | ||||
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not set, and | If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not set, and | |||
if the server has the following confirmed | if the server has the following confirmed | |||
record, then this request is likely the result | record, then this request is likely the result | |||
of a chance collision between the values of | of a chance collision between the values of | |||
the eia_clientowner.co_ownerid subfield of | the eia_clientowner.co_ownerid subfield of | |||
EXCHANGE_ID4args for two different clients. | EXCHANGE_ID4args for two different clients. | |||
</t> | </t> | |||
<t> | <t> | |||
{ ownerid_arg, *, old_principal_arg, old_clientid_ret, confirmed } | { ownerid_arg, *, old_principal_arg, old_clientid_ret, confirmed } | |||
</t> | </t> | |||
<t> | <t> | |||
If there is currently no state associated with old_clientid_ret, | If there is currently no state associated with old_clientid_ret, | |||
or if there is state but the lease has expired, then | or if there is state but the lease has expired, then | |||
this case is effectively equivalent to the | this case is effectively equivalent to the | |||
New Owner ID case of <xref target="case_new_owner_id"/>. | New Owner ID case of <xref target="case_new_owner_id" format="defaul t"/>. | |||
The confirmed record is deleted, the old_clientid_ret and its | The confirmed record is deleted, the old_clientid_ret and its | |||
lock state are deleted, | lock state are deleted, | |||
a new shorthand client ID | a new shorthand client ID | |||
is generated, and the following unconfirmed | is generated, and the following unconfirmed | |||
record is added to the server's state. | record is added to the server's state. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
{ ownerid_arg, verifier_arg, principal_arg, clientid_ret, unconfirmed } | { ownerid_arg, verifier_arg, principal_arg, clientid_ret, unconfirmed } | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
Subsequently, the server returns clientid_ret. | Subsequently, the server returns clientid_ret. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
</t> | ||||
<t> | ||||
If old_clientid_ret has an unexpired lease with state, then | If old_clientid_ret has an unexpired lease with state, then | |||
no state of old_clientid_ret is changed or deleted. | no state of old_clientid_ret is changed or deleted. | |||
The server returns NFS4ERR_CLID_INUSE | The server returns NFS4ERR_CLID_INUSE | |||
to indicate that the client should | to indicate that the client should | |||
retry with a different value for the | retry with a different value for the | |||
eia_clientowner.co_ownerid subfield of | eia_clientowner.co_ownerid subfield of | |||
EXCHANGE_ID4args. The client record is not changed. | EXCHANGE_ID4args. The client record is not changed.</t> | |||
</t> | </li> | |||
</list> | ||||
</t> | ||||
<t anchor="case_retry">Replacement of Unconfirmed Record | <li anchor="case_retry"> | |||
<list style="empty"> | <t>Replacement of Unconfirmed Record | |||
<t> | </t> | |||
<t> | ||||
If the EXCHGID4_FLAG_UPD_CONFIRMED_REC_A flag is not set, | If the EXCHGID4_FLAG_UPD_CONFIRMED_REC_A flag is not set, | |||
and the server has the following unconfirmed record, then | and the server has the following unconfirmed record, then | |||
the client is attempting EXCHANGE_ID again on an | the client is attempting EXCHANGE_ID again on an | |||
unconfirmed client ID, perhaps due to a retry, a client | unconfirmed client ID, perhaps due to a retry, a client | |||
restart before client ID confirmation (i.e., | restart before client ID confirmation (i.e., | |||
before CREATE_SESSION was called), or | before CREATE_SESSION was called), or | |||
some other reason. | some other reason. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
{ ownerid_arg, *, *, old_clientid_ret, unconfirmed } | { ownerid_arg, *, *, old_clientid_ret, unconfirmed } | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
It is possible that | It is possible that | |||
the properties of old_clientid_ret are | the properties of old_clientid_ret are | |||
different than those specified in the current | different than those specified in the current | |||
EXCHANGE_ID. Whether or not the properties are being updated, | EXCHANGE_ID. Whether or not the properties are being updated, | |||
to eliminate ambiguity, the server | to eliminate ambiguity, the server | |||
deletes the unconfirmed record, generates a | deletes the unconfirmed record, generates a | |||
new client ID (clientid_ret), and establishes | new client ID (clientid_ret), and establishes | |||
the following unconfirmed record: | the following unconfirmed record: | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
{ ownerid_arg, verifier_arg, principal_arg, clientid_ret, unconfirmed } | { ownerid_arg, verifier_arg, principal_arg, clientid_ret, unconfirmed } | |||
<vspace blankLines='1' /> | </t> | |||
</t> | </li> | |||
</list> | ||||
</t> | ||||
<t anchor="case_client_restart">Client Restart | <li anchor="case_client_restart"> | |||
<list style="empty"> | <t>Client Restart</t> | |||
<t> | <t> | |||
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not set, and | If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is not set, and | |||
if the server has the following confirmed client record, then | if the server has the following confirmed client record, then | |||
this request is likely from a previously confirmed client | this request is likely from a previously confirmed client | |||
that has restarted. | that has restarted. | |||
</t> | </t> | |||
<t> | <t> | |||
{ ownerid_arg, old_verifier_arg, principal_arg, old_clientid_ret, con firmed } | { ownerid_arg, old_verifier_arg, principal_arg, old_clientid_ret, con firmed } | |||
</t> | </t> | |||
<t> | <t> | |||
Since the previous incarnation of the same | Since the previous incarnation of the same | |||
client will no longer be making requests, | client will no longer be making requests, | |||
once the new client ID is confirmed by | once the new client ID is confirmed by | |||
CREATE_SESSION, byte-range locks and share reservations | CREATE_SESSION, byte-range locks and share reservations | |||
should be released immediately rather than | should be released immediately rather than | |||
forcing the new incarnation to wait for | forcing the new incarnation to wait for | |||
the lease time on the previous incarnation | the lease time on the previous incarnation | |||
to expire. Furthermore, session state should | to expire. Furthermore, session state should | |||
be removed since if the client had maintained | be removed since if the client had maintained | |||
that information across restart, this request | that information across restart, this request | |||
would not have been sent. If the server | would not have been sent. If the server | |||
supports neither the CLAIM_DELEGATE_PREV | supports neither the CLAIM_DELEGATE_PREV | |||
nor CLAIM_DELEG_PREV_FH | nor CLAIM_DELEG_PREV_FH | |||
claim types, associated delegations should be | claim types, associated delegations should be | |||
purged as well; otherwise, delegations are | purged as well; otherwise, delegations are | |||
retained and recovery proceeds according to | retained and recovery proceeds according to | |||
<xref target="delegation_recovery"/>. | <xref target="delegation_recovery" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
After processing, clientid_ret is returned to the client and | After processing, clientid_ret is returned to the client and | |||
this client record is added: | this client record is added: | |||
</t> | </t> | |||
<t> | <t> | |||
{ ownerid_arg, verifier_arg, principal_arg, clientid_ret, unconfirmed } | { ownerid_arg, verifier_arg, principal_arg, clientid_ret, unconfirmed } | |||
<vspace blankLines='1' /> | </t> | |||
</t> | <t> | |||
<t> | ||||
The previously described confirmed record | The previously described confirmed record | |||
continues to exist, and thus the same | continues to exist, and thus the same | |||
ownerid_arg exists in both a confirmed and | ownerid_arg exists in both a confirmed and | |||
unconfirmed state at the same time. The number | unconfirmed state at the same time. The number | |||
of states can collapse to one once the server | of states can collapse to one once the server | |||
receives an applicable CREATE_SESSION or | receives an applicable CREATE_SESSION or | |||
EXCHANGE_ID. | EXCHANGE_ID. | |||
</t> | ||||
<list style='symbols'> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
If the server subsequently receives a successful | If the server subsequently receives a successful | |||
CREATE_SESSION that confirms clientid_ret, | CREATE_SESSION that confirms clientid_ret, | |||
then the server atomically destroys the | then the server atomically destroys the | |||
confirmed record and makes the unconfirmed | confirmed record and makes the unconfirmed | |||
record confirmed as described in | record confirmed as described in | |||
<xref target="OP_CREATE_SESSION_DESCRIPTION" />. | <xref target="OP_CREATE_SESSION_DESCRIPTION" format="default"/>. | |||
</li> | ||||
</t> | <li> | |||
<t> | ||||
If the server instead subsequently receives | If the server instead subsequently receives | |||
an EXCHANGE_ID with the client owner equal | an EXCHANGE_ID with the client owner equal | |||
to ownerid_arg, one strategy is to simply | to ownerid_arg, one strategy is to simply | |||
delete the unconfirmed record, and process the | delete the unconfirmed record, and process the | |||
EXCHANGE_ID as described in the entirety of | EXCHANGE_ID as described in the entirety of | |||
<xref target="OP_EXCHANGE_ID_IMPLEMENTATION" | <xref target="OP_EXCHANGE_ID_IMPLEMENTATION" format="default"/>. | |||
/>. | </li> | |||
</ul> | ||||
</t> | </li> | |||
</list> | ||||
</t> | ||||
</list> | ||||
</t> | ||||
<t anchor="case_update">Update | <li anchor="case_update"> | |||
<list style="empty"> | <t>Update | |||
<t> | </t> | |||
<t> | ||||
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set, and the | If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set, and the | |||
server has the following confirmed record, | server has the following confirmed record, | |||
then this request is an attempt at an update. | then this request is an attempt at an update. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
{ ownerid_arg, verifier_arg, principal_arg, clientid_ret, confirmed } | { ownerid_arg, verifier_arg, principal_arg, clientid_ret, confirmed } | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
Since the record has been confirmed, the client must have | Since the record has been confirmed, the client must have | |||
received the server's reply from the initial EXCHANGE_ID | received the server's reply from the initial EXCHANGE_ID | |||
request. The server allows the update, and the client record | request. The server allows the update, and the client record | |||
is left intact. | is left intact. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | ||||
<t anchor="case_update_noent">Update but No Confirmed Record | <li anchor="case_update_noent"> | |||
<list style="empty"> | <t>Update but No Confirmed Record | |||
<t> | </t> | |||
<t> | ||||
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set, and the | If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set, and the | |||
server has no confirmed record corresponding ownerid_arg, | server has no confirmed record corresponding ownerid_arg, | |||
then the server returns NFS4ERR_NOENT and leaves any unconfirmed | then the server returns NFS4ERR_NOENT and leaves any unconfirmed | |||
record intact. | record intact. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | ||||
<t anchor="case_update_exist">Update but Wrong Verifier | <li anchor="case_update_exist"> | |||
<list style="empty"> | <t>Update but Wrong Verifier | |||
<t> | </t> | |||
<t> | ||||
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set, and the | If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set, and the | |||
server has the following confirmed record, | server has the following confirmed record, | |||
then this request is an illegal attempt at an | then this request is an illegal attempt at an | |||
update, perhaps because of a retry from a previous client | update, perhaps because of a retry from a previous client | |||
incarnation. | incarnation. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
{ ownerid_arg, old_verifier_arg, *, clientid_ret, confirmed } | { ownerid_arg, old_verifier_arg, *, clientid_ret, confirmed } | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
The server returns NFS4ERR_NOT_SAME and leaves the client record | The server returns NFS4ERR_NOT_SAME and leaves the client record | |||
intact. | intact. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | ||||
<t anchor="case_update_perm">Update but Wrong Principal | <li anchor="case_update_perm"> | |||
<list style="empty"> | <t>Update but Wrong Principal | |||
<t> | </t> | |||
<t> | ||||
If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set, and the | If EXCHGID4_FLAG_UPD_CONFIRMED_REC_A is set, and the | |||
server has the following confirmed record, | server has the following confirmed record, | |||
then this request is an illegal attempt at an | then this request is an illegal attempt at an | |||
update by an unauthorized principal. | update by an unauthorized principal. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
{ ownerid_arg, verifier_arg, old_principal_arg, clientid_ret, confirmed } | { ownerid_arg, verifier_arg, old_principal_arg, clientid_ret, confirmed } | |||
</t> | ||||
<vspace blankLines='1' /> | <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> | |||
</list> | </li> | |||
</t> | </ol> | |||
</list> | ||||
</t> | ||||
</section> | </section> | |||
</section> | ||||
</section> | <section anchor="OP_CREATE_SESSION" numbered="true" toc="default"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>Operation 43: CREATE_SESSION - Create New Session and Confirm Clie | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | nt ID</name> | |||
$ --> | <section toc="exclude" anchor="OP_CREATE_SESSION_ARGUMENT" numbered="tru | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | e"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENT</name> | |||
<section anchor="OP_CREATE_SESSION" title="Operation 43: CREATE_SESSION - Create | <sourcecode type="xdr"><![CDATA[ | |||
New Session and Confirm Client ID" > | ||||
<section toc="exclude" anchor="OP_CREATE_SESSION_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
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>; | |||
}; | }; | |||
const CREATE_SESSION4_FLAG_PERSIST = 0x00000001; | const CREATE_SESSION4_FLAG_PERSIST = 0x00000001; | |||
const CREATE_SESSION4_FLAG_CONN_BACK_CHAN = 0x00000002; | const CREATE_SESSION4_FLAG_CONN_BACK_CHAN = 0x00000002; | |||
const CREATE_SESSION4_FLAG_CONN_RDMA = 0x00000004; | const CREATE_SESSION4_FLAG_CONN_RDMA = 0x00000004; | |||
struct CREATE_SESSION4args { | struct CREATE_SESSION4args { | |||
clientid4 csa_clientid; | clientid4 csa_clientid; | |||
sequenceid4 csa_sequence; | sequenceid4 csa_sequence; | |||
uint32_t csa_flags; | uint32_t csa_flags; | |||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_CREATE_SESSION_RESULT" numbered="true" | |||
</figure> | > | |||
</section> | <name>RESULT</name> | |||
<section toc="exclude" anchor="OP_CREATE_SESSION_RESULT" title="RESULT"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
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; | |||
}; | }; | |||
union CREATE_SESSION4res switch (nfsstat4 csr_status) { | union CREATE_SESSION4res switch (nfsstat4 csr_status) { | |||
case NFS4_OK: | case NFS4_OK: | |||
CREATE_SESSION4resok csr_resok4; | CREATE_SESSION4resok csr_resok4; | |||
default: | default: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_CREATE_SESSION_DESCRIPTION" numbered=" | |||
</figure> | true"> | |||
</section> | <name>DESCRIPTION</name> | |||
<section toc="exclude" anchor="OP_CREATE_SESSION_DESCRIPTION" title="DESCRIPTI | <t> | |||
ON"> | ||||
<t> | ||||
This operation is used by the client to create new session objects | This operation is used by the client to create new session objects | |||
on the server. | on the server. | |||
</t> | </t> | |||
<t> | <t> | |||
CREATE_SESSION can be sent with or without a preceding SEQUENCE | CREATE_SESSION can be sent with or without a preceding SEQUENCE | |||
operation in the same COMPOUND procedure. | operation in the same COMPOUND procedure. | |||
If CREATE_SESSION is sent with a preceding SEQUENCE | If CREATE_SESSION is sent with a preceding SEQUENCE | |||
operation, | operation, | |||
any session created by CREATE_SESSION has no direct | any session created by CREATE_SESSION has no direct | |||
relation to the session specified in the SEQUENCE operation, although | relation to the session specified in the SEQUENCE operation, although | |||
the two sessions might be associated with the same client ID. | the two sessions might be associated with the same client ID. | |||
If CREATE_SESSION is sent without a preceding SEQUENCE, then it | If CREATE_SESSION is sent without a preceding SEQUENCE, then it | |||
MUST be the only operation in the COMPOUND procedure's request. If | <bcp14>MUST</bcp14> be the only operation in the COMPOUND procedure's requ | |||
it is not, the server MUST return NFS4ERR_NOT_ONLY_OP. | est. If | |||
</t> | it is not, the server <bcp14>MUST</bcp14> return NFS4ERR_NOT_ONLY_OP. | |||
<t> | </t> | |||
<t> | ||||
In addition to creating a session, CREATE_SESSION has the following | In addition to creating a session, CREATE_SESSION has the following | |||
effects: | effects: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The first session created with a new | The first session created with a new | |||
client ID serves to confirm the | client ID serves to confirm the | |||
creation of that | creation of that | |||
client's state on the server. The server returns the parameter | client's state on the server. The server returns the parameter | |||
values for the new session. | values for the new session. | |||
</t> | </li> | |||
<t> | <li> | |||
The connection CREATE_SESSION that is sent over is associated with the | The connection CREATE_SESSION that is sent over is associated with the | |||
session's fore channel. | session's fore channel. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The arguments and results of CREATE_SESSION are described as follows: | The arguments and results of CREATE_SESSION are described as follows: | |||
<list style="hanging"> | </t> | |||
<t hangText="csa_clientid:"/> | <dl newline="false" spacing="normal"> | |||
<t> | <dt>csa_clientid:</dt> | |||
<dd> | ||||
This is the client ID with which the new session will be associated. | This is the client ID with which the new session will be associated. | |||
The corresponding result is csr_sessionid, the session ID | The corresponding result is csr_sessionid, the session ID | |||
of the new session. | of the new session. | |||
</t> | </dd> | |||
<t hangText="csa_sequence:"/> | <dt>csa_sequence:</dt> | |||
<t> | <dd> | |||
Each client ID serializes CREATE_SESSION via a per-client ID | Each client ID serializes CREATE_SESSION via a per-client ID | |||
sequence number (see | sequence number (see | |||
<xref target="OP_CREATE_SESSION_IMPLEMENTATION" />). | <xref target="OP_CREATE_SESSION_IMPLEMENTATION" format="default"/>). | |||
The corresponding result is csr_sequence, which MUST be equal to | The corresponding result is csr_sequence, which <bcp14>MUST</bcp14> be | |||
equal to | ||||
csa_sequence. | csa_sequence. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | <t> | |||
<t> | ||||
In the next three arguments, the client offers a value | In the next three arguments, the client offers a value | |||
that is to be a property of the session. Except where | that is to be a property of the session. Except where | |||
stated otherwise, it is RECOMMENDED that | stated otherwise, it is <bcp14>RECOMMENDED</bcp14> that | |||
the server accept the value. | the server accept the value. | |||
If it is not acceptable, the server MAY use a different value. | If it is not acceptable, the server <bcp14>MAY</bcp14> use a different va | |||
Regardless, the server MUST return the value the session will | lue. | |||
Regardless, the server <bcp14>MUST</bcp14> return the value the session w | ||||
ill | ||||
use (which will be either what the client offered, or what | use (which will be either what the client offered, or what | |||
the server is insisting on) to the client. | the server is insisting on) to the client. | |||
<list style="hanging"> | </t> | |||
<t hangText="csa_flags:"/> | <dl newline="false" spacing="normal"> | |||
<t> | <dt>csa_flags:</dt> | |||
<dd> | ||||
<t> | ||||
The csa_flags field contains a list of the following flag | The csa_flags field contains a list of the following flag | |||
bits: | bits: | |||
<list style="hanging"> | </t> | |||
<t hangText="CREATE_SESSION4_FLAG_PERSIST:"/> | ||||
<t> | <dl newline="true" spacing="normal"> | |||
<dt>CREATE_SESSION4_FLAG_PERSIST:</dt> | ||||
<dd> | ||||
<t> | ||||
If CREATE_SESSION4_FLAG_PERSIST is set, the client | If CREATE_SESSION4_FLAG_PERSIST is set, the client | |||
wants the server to provide a persistent reply cache. | wants the server to provide a persistent reply cache. | |||
For sessions in which only idempotent operations | For sessions in which only idempotent operations | |||
will be used (e.g., a read-only session), clients | will be used (e.g., a read-only session), clients | |||
SHOULD NOT set CREATE_SESSION4_FLAG_PERSIST. If | <bcp14>SHOULD NOT</bcp14> set CREATE_SESSION4_FLAG_PERSIST. If | |||
the server does not or cannot provide a persistent reply cache, | the server does not or cannot provide a persistent reply cache, | |||
the server MUST NOT set CREATE_SESSION4_FLAG_PERSIST in | the server <bcp14>MUST NOT</bcp14> set CREATE_SESSION4_FLAG_PERSIST i n | |||
the field csr_flags. | the field csr_flags. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
If the server is a pNFS metadata server, for | If the server is a pNFS metadata server, for | |||
reasons described in <xref target="obtaining_layout" /> | reasons described in <xref target="obtaining_layout" format="default | |||
it SHOULD support CREATE_SESSION4_FLAG_PERSIST if it | "/> | |||
supports the layout_hint (<xref target="attrdef_layout_hint" />) | it <bcp14>SHOULD</bcp14> support CREATE_SESSION4_FLAG_PERSIST if it | |||
supports the layout_hint (<xref target="attrdef_layout_hint" format= | ||||
"default"/>) | ||||
attribute. | attribute. | |||
</t> | ||||
</dd> | ||||
</t> | <dt>CREATE_SESSION4_FLAG_CONN_BACK_CHAN:</dt> | |||
<t hangText="CREATE_SESSION4_FLAG_CONN_BACK_CHAN:"/> | <dd> | |||
<t> | ||||
If CREATE_SESSION4_FLAG_CONN_BACK_CHAN is set in csa_flags, | If CREATE_SESSION4_FLAG_CONN_BACK_CHAN is set in csa_flags, | |||
the client is requesting that the connection over which the | the client is requesting that the connection over which the | |||
CREATE_SESSION operation arrived be associated with the session's | CREATE_SESSION operation arrived be associated with the session's | |||
backchannel in addition to its fore channel. | backchannel in addition to its fore channel. | |||
If the server agrees, it | If the server agrees, it | |||
sets CREATE_SESSION4_FLAG_CONN_BACK_CHAN | sets CREATE_SESSION4_FLAG_CONN_BACK_CHAN | |||
in the result field csr_flags. If | in the result field csr_flags. If | |||
CREATE_SESSION4_FLAG_CONN_BACK_CHAN is not set in csa_flags, | CREATE_SESSION4_FLAG_CONN_BACK_CHAN is not set in csa_flags, | |||
then CREATE_SESSION4_FLAG_CONN_BACK_CHAN MUST NOT be set | then CREATE_SESSION4_FLAG_CONN_BACK_CHAN <bcp14>MUST NOT</bcp14> be set | |||
in csr_flags. | in csr_flags. | |||
</dd> | ||||
</t> | <dt>CREATE_SESSION4_FLAG_CONN_RDMA:</dt> | |||
<t hangText="CREATE_SESSION4_FLAG_CONN_RDMA:"/> | <dd> | |||
<t> | ||||
If CREATE_SESSION4_FLAG_CONN_RDMA is set in csa_flags, | If CREATE_SESSION4_FLAG_CONN_RDMA is set in csa_flags, | |||
and if the connection over which the CREATE_SESSION operation | and if the connection over which the CREATE_SESSION operation | |||
arrived | arrived | |||
is currently in non-RDMA mode but | is currently in non-RDMA mode but | |||
has the capability to operate in RDMA mode, then the client | has the capability to operate in RDMA mode, then the client | |||
is requesting that the server "step up" to RDMA mode | is requesting that the server "step up" to RDMA mode | |||
on the connection. | on the connection. | |||
If the server agrees, it sets | If the server agrees, it sets | |||
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 MUST | not set in csa_flags, then CREATE_SESSION4_FLAG_CONN_RDMA <bcp14>MUS | |||
NOT be set in csr_flags. | T | |||
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 | |||
MUST exchange all future traffic on the connection with RPC RDMA | <bcp14>MUST</bcp14> exchange all future traffic on the connection wi | |||
framing and not Record Marking (<xref target="RFC8166" />). | th RPC RDMA | |||
</t> | framing and not Record Marking (<xref target="RFC8166" format="defau | |||
</list> | lt"/>). | |||
</t> | </dd> | |||
<t hangText="csa_fore_chan_attrs, csa_fore_chan_attrs:"/> | </dl> | |||
<t> | </dd> | |||
<dt>csa_fore_chan_attrs, csa_back_chan_attrs:</dt> | ||||
<dd> | ||||
<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. | |||
The results establish attributes for each channel, and | The results establish attributes for each channel, and | |||
on all subsequent use of each channel of the session. | on all subsequent use of each channel of the session. | |||
Each structure has the following fields: | Each structure has the following fields: | |||
<list style="hanging"> | </t> | |||
<t hangText="ca_headerpadsize:"/> | ||||
<t> | <dl newline="true" spacing="normal"> | |||
<dt>ca_headerpadsize:</dt> | ||||
<dd> | ||||
<t> | ||||
The maximum amount of padding the requester is willing to apply | The maximum amount of padding the requester is willing to apply | |||
to ensure that write payloads are aligned on some boundary at | to ensure that write payloads are aligned on some boundary at | |||
the replier. For each channel, the server | the replier. For each channel, the server | |||
<list style="symbols"> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <li> | |||
will reply in ca_headerpadsize with | will reply in ca_headerpadsize with | |||
its preferred value, | its preferred value, | |||
or zero if padding is not in use, and | or zero if padding is not in use, and | |||
</t> | </li> | |||
<li> | ||||
<t> | <bcp14>MAY</bcp14> decrease this value but <bcp14>MUST NOT</bcp14> | |||
MAY decrease this value but MUST NOT increase it. | increase it. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </dd> | |||
<t hangText="ca_maxrequestsize:"/> | <dt>ca_maxrequestsize:</dt> | |||
<t> | <dd> | |||
The maximum size of a COMPOUND or CB_COMPOUND request that | The maximum size of a COMPOUND or CB_COMPOUND request that | |||
will be sent. This size represents the XDR encoded size of | will be sent. This size represents the XDR encoded size of | |||
the request, including the RPC headers (including | the request, including the RPC headers (including | |||
security flavor credentials and verifiers) | security flavor credentials and verifiers) | |||
but excludes any RPC transport framing headers. | but excludes any RPC transport framing headers. | |||
Imagine a request coming over a non-RDMA TCP/IP connection, and | Imagine a request coming over a non-RDMA TCP/IP connection, and | |||
that it has a single Record Marking header preceding | that it has a single Record Marking header preceding | |||
it. The maximum allowable | it. The maximum allowable | |||
count encoded in the header will be | count encoded in the header will be | |||
ca_maxrequestsize. If a requester sends | ca_maxrequestsize. If a requester sends | |||
a request that exceeds ca_maxrequestsize, the error | a request that exceeds ca_maxrequestsize, the error | |||
NFS4ERR_REQ_TOO_BIG will be returned per the description in | NFS4ERR_REQ_TOO_BIG will be returned per the description in | |||
<xref target="COMPOUND_Sizing_Issues" />. | <xref target="COMPOUND_Sizing_Issues" format="default"/>. | |||
For each channel, | For each channel, | |||
the server MAY decrease this value but MUST NOT increase it. | the server <bcp14>MAY</bcp14> decrease this value but <bcp14>MUST NO T</bcp14> increase it. | |||
</t> | </dd> | |||
<t hangText="ca_maxresponsesize:"/> | <dt>ca_maxresponsesize:</dt> | |||
<t> | <dd> | |||
The maximum size of a COMPOUND or CB_COMPOUND reply that | The maximum size of a COMPOUND or CB_COMPOUND reply that | |||
the requester will | the requester will | |||
accept from the replier including RPC headers (see | accept from the replier including RPC headers (see | |||
the ca_maxrequestsize definition). | the ca_maxrequestsize definition). | |||
For each channel, the server MAY decrease this value, but MUST | For each channel, the server <bcp14>MAY</bcp14> decrease this value, | |||
NOT increase it. | but <bcp14>MUST | |||
NOT</bcp14> increase it. | ||||
However, if the client selects a value for | However, if the client selects a value for | |||
ca_maxresponsesize such that a replier on a channel could | ca_maxresponsesize such that a replier on a channel could | |||
never send a response, the server SHOULD return | never send a response, the server <bcp14>SHOULD</bcp14> return | |||
NFS4ERR_TOOSMALL in the CREATE_SESSION reply. | NFS4ERR_TOOSMALL in the CREATE_SESSION reply. | |||
After the session is created, if a requester sends a | After the session is created, if a requester sends a | |||
request for which the size of the reply would exceed | request for which the size of the reply would exceed | |||
this value, the replier will return NFS4ERR_REP_TOO_BIG, | this value, the replier will return NFS4ERR_REP_TOO_BIG, | |||
per the description in | per the description in | |||
<xref target="COMPOUND_Sizing_Issues" />. | <xref target="COMPOUND_Sizing_Issues" format="default"/>. | |||
</t> | </dd> | |||
<t hangText="ca_maxresponsesize_cached:"/> | <dt>ca_maxresponsesize_cached:</dt> | |||
<t> | <dd> | |||
Like ca_maxresponsesize, but the maximum size of a reply | Like ca_maxresponsesize, but the maximum size of a reply | |||
that will be stored in the reply cache | that will be stored in the reply cache | |||
(<xref target="Slot_Identifiers_and_Server_Reply_Cache" />). | (<xref target="Slot_Identifiers_and_Server_Reply_Cache" format="defa ult"/>). | |||
For each channel, the server MAY decrease this value, but MUST | For each channel, the server <bcp14>MAY</bcp14> decrease this | |||
NOT increase it. | value, but <bcp14>MUST NOT</bcp14> increase it. | |||
If, in the reply to CREATE_SESSION, the value of | If, in the reply to CREATE_SESSION, the value of | |||
ca_maxresponsesize_cached of a channel is less than the value | ca_maxresponsesize_cached of a channel is less than the value | |||
of ca_maxresponsesize of the same channel, then this is an | of ca_maxresponsesize of the same channel, then this is an | |||
indication to the requester that it needs to be selective | indication to the requester that it needs to be selective | |||
about which replies it directs the replier to cache; for | about which replies it directs the replier to cache; for | |||
example, large replies from nonidempotent operations (e.g., | example, large replies from non-idempotent operations (e.g., | |||
COMPOUND requests with a READ operation) should not be | COMPOUND requests with a READ operation) should not be | |||
cached. The requester decides which replies to cache via an | cached. The requester decides which replies to cache via an | |||
argument to the SEQUENCE (the sa_cachethis field, see <xref | argument to the SEQUENCE (the sa_cachethis field, see <xref target=" | |||
target="OP_SEQUENCE" />) or CB_SEQUENCE (the csa_cachethis | OP_SEQUENCE" format="default"/>) or CB_SEQUENCE (the csa_cachethis | |||
field, see <xref target="OP_CB_SEQUENCE" />) operations. | field, see <xref target="OP_CB_SEQUENCE" format="default"/>) operati | |||
ons. | ||||
After the session is created, if a requester sends a | After the session is created, if a requester sends a | |||
request for which the size of the reply would exceed | request for which the size of the reply would exceed | |||
ca_maxresponsesize_cached, the replier will return | ca_maxresponsesize_cached, the replier will return | |||
NFS4ERR_REP_TOO_BIG_TO_CACHE, per the description in <xref | NFS4ERR_REP_TOO_BIG_TO_CACHE, per the description in <xref target="C | |||
target="COMPOUND_Sizing_Issues" />. | OMPOUND_Sizing_Issues" format="default"/>. | |||
</t> | </dd> | |||
<t hangText="ca_maxoperations:"/> | <dt>ca_maxoperations:</dt> | |||
<t> | <dd> | |||
The maximum number of operations the replier | The maximum number of operations the replier | |||
will accept in a COMPOUND or CB_COMPOUND. | will accept in a COMPOUND or CB_COMPOUND. | |||
For the backchannel, the server MUST NOT change the value the | For the backchannel, the server <bcp14>MUST NOT</bcp14> change the v alue the | |||
client offers. For the fore channel, the server | client offers. For the fore channel, the server | |||
MAY change the requested value. | <bcp14>MAY</bcp14> change the requested value. | |||
After the session is created, if a requester sends a | After the session is created, if a requester sends a | |||
COMPOUND or CB_COMPOUND | COMPOUND or CB_COMPOUND | |||
with more operations than ca_maxoperations, | with more operations than ca_maxoperations, | |||
the replier MUST return NFS4ERR_TOO_MANY_OPS. | the replier <bcp14>MUST</bcp14> return NFS4ERR_TOO_MANY_OPS. | |||
</t> | </dd> | |||
<t hangText="ca_maxrequests:"/> | <dt>ca_maxrequests:</dt> | |||
<t> | <dd> | |||
The maximum number of concurrent COMPOUND or CB_COMPOUND | The maximum number of concurrent COMPOUND or CB_COMPOUND | |||
requests the requester will send on the session. Subsequent | requests the requester will send on the session. Subsequent | |||
requests will each be assigned a slot identifier by the requester | requests will each be assigned a slot identifier by the requester | |||
within the range zero to ca_maxrequests - 1 inclusive. | within the range zero to ca_maxrequests - 1 inclusive. | |||
For the backchannel, the server MUST NOT change the value the | For the backchannel, the server <bcp14>MUST NOT</bcp14> change the v alue the | |||
client offers. For the fore channel, the server | client offers. For the fore channel, the server | |||
MAY change the requested value. | <bcp14>MAY</bcp14> change the requested value. | |||
</t> | </dd> | |||
<t hangText="ca_rdma_ird:"/> | <dt>ca_rdma_ird:</dt> | |||
<t> | <dd> | |||
This array has a maximum of one element. | This array has a maximum of one element. | |||
If this array has one element, then the element contains the | If this array has one element, then the element contains the | |||
inbound RDMA read queue depth (IRD). | inbound RDMA read queue depth (IRD). | |||
For each channel, the server MAY decrease this value, but MUST | For each channel, the server <bcp14>MAY</bcp14> decrease this value, | |||
NOT increase it. | but <bcp14>MUST | |||
</t> | NOT</bcp14> increase it. | |||
</list> | </dd></dl></dd> | |||
</t> | ||||
<t hangText="csa_cb_program"/> | <dt>csa_cb_program</dt> | |||
<t> | <dd> | |||
This is the ONC RPC program number the server MUST use in | This is the ONC RPC program number the server <bcp14>MUST</bcp14> use | |||
in | ||||
any callbacks sent through the backchannel to the client. | any callbacks sent through the backchannel to the client. | |||
The server MUST specify an ONC RPC program number equal to | The server <bcp14>MUST</bcp14> specify an ONC RPC program number equal to | |||
csa_cb_program and an ONC RPC version number equal to 4 in | csa_cb_program and an ONC RPC version number equal to 4 in | |||
callbacks sent to the client. If a CB_COMPOUND is | callbacks sent to the client. If a CB_COMPOUND is | |||
sent to the client, the server MUST use a minor version | sent to the client, the server <bcp14>MUST</bcp14> use a minor version | |||
number of 1. | number of 1. | |||
There is no corresponding result. | There is no corresponding result. | |||
</t> | </dd> | |||
<t hangText="csa_sec_parms"/> | <dt>csa_sec_parms</dt> | |||
<t> | <dd> | |||
<t> | ||||
The field csa_sec_parms is an array of acceptable | The field csa_sec_parms is an array of acceptable | |||
security credentials the server can use on | security credentials the server can use on | |||
the session's backchannel. Three security | the session's backchannel. Three security | |||
flavors are supported: AUTH_NONE, AUTH_SYS, | flavors are supported: AUTH_NONE, AUTH_SYS, | |||
and RPCSEC_GSS. If AUTH_NONE is specified for | and RPCSEC_GSS. If AUTH_NONE is specified for | |||
a credential, then this says the client is | a credential, then this says the client is | |||
authorizing the server to use AUTH_NONE on | authorizing the server to use AUTH_NONE on | |||
all callbacks for the session. If AUTH_SYS | all callbacks for the session. If AUTH_SYS | |||
is specified, then the client is authorizing | is specified, then the client is authorizing | |||
the server to use AUTH_SYS on all callbacks, | the server to use AUTH_SYS on all callbacks, | |||
using the credential specified cbsp_sys_cred. If | using the credential specified cbsp_sys_cred. If | |||
RPCSEC_GSS is specified, then the server is | RPCSEC_GSS is specified, then the server is | |||
allowed to use the RPCSEC_GSS context specified | allowed to use the RPCSEC_GSS context specified | |||
in cbsp_gss_parms as the RPCSEC_GSS context in | in cbsp_gss_parms as the RPCSEC_GSS context in | |||
the credential of the RPC header of callbacks | the credential of the RPC header of callbacks | |||
to the client. | to the client. | |||
There is no corresponding result. | There is no corresponding result. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
The RPCSEC_GSS context for the backchannel is specified via | The RPCSEC_GSS context for the backchannel is specified via | |||
a pair of values of data type | a pair of values of data type | |||
gsshandle4_t. The data type gsshandle4_t represents an | gsshandle4_t. The data type gsshandle4_t represents an | |||
RPCSEC_GSS handle, and is | RPCSEC_GSS handle, and is | |||
precisely the same as the data type of the "handle" field of | precisely the same as the data type of the "handle" field of | |||
the rpc_gss_init_res data type defined in | the rpc_gss_init_res data type defined in "Context Creation Response | |||
Section 5.2.3.1, "Context Creation Response - | - Successful Acceptance", <xref target="RFC2203" sectionFormat="of" sec | |||
Successful Acceptance", of <xref target="RFC2203" | tion="5.2.3.1"/>. | |||
/>. | </t> | |||
<t> | ||||
<vspace blankLines='1' /> | ||||
The first RPCSEC_GSS handle, gcbp_handle_from_server, | The first RPCSEC_GSS handle, gcbp_handle_from_server, | |||
is the fore handle the server returned to | is the fore handle the server returned to | |||
the client (either in the handle field of data type | the client (either in the handle field of data type | |||
rpc_gss_init_res or as one of the elements of the spi_handles | rpc_gss_init_res or as one of the elements of the spi_handles | |||
field returned in the reply to EXCHANGE_ID) when the RPCSEC_GSS contex t | field returned in the reply to EXCHANGE_ID) when the RPCSEC_GSS contex t | |||
was created on the server. The second handle, | was created on the server. The second handle, | |||
gcbp_handle_from_client, is the back handle to which the | gcbp_handle_from_client, is the back handle to which the | |||
client will map the RPCSEC_GSS context. The | client will map the RPCSEC_GSS context. The | |||
server can immediately use the value of | server can immediately use the value of | |||
gcbp_handle_from_client in the RPCSEC_GSS credential | gcbp_handle_from_client in the RPCSEC_GSS credential | |||
in callback RPCs. That is, the value in | in callback RPCs. That is, the value in | |||
gcbp_handle_from_client can be used as the | gcbp_handle_from_client can be used as the | |||
value of the field "handle" in data type | value of the field "handle" in data type | |||
rpc_gss_cred_t (see Section 5, "Elements of | rpc_gss_cred_t (see "Elements of | |||
the RPCSEC_GSS Security Protocol", of <xref | the RPCSEC_GSS Security Protocol", <xref target="RFC2203" sectionForma | |||
target="RFC2203" />) in callback RPCs. | t="of" section="5"/>) in callback RPCs. | |||
The server MUST use the RPCSEC_GSS security service | The server <bcp14>MUST</bcp14> use the RPCSEC_GSS security service | |||
specified in gcbp_service, i.e., it MUST set the | specified in gcbp_service, i.e., it <bcp14>MUST</bcp14> set the | |||
"service" field of the rpc_gss_cred_t data type in | "service" field of the rpc_gss_cred_t data type in | |||
RPCSEC_GSS credential to the value of gcbp_service (see | RPCSEC_GSS credential to the value of gcbp_service (see | |||
Section 5.3.1, "RPC Request Header", of <xref target="RFC2203" />). | "RPC Request Header", <xref target="RFC2203" sectionFormat="of" sectio | |||
n="5.3.1"/>). | ||||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
If the RPCSEC_GSS handle identified by | If the RPCSEC_GSS handle identified by | |||
gcbp_handle_from_server does not exist on the server, | gcbp_handle_from_server does not exist on the server, | |||
the server will return NFS4ERR_NOENT. | the server will return NFS4ERR_NOENT. | |||
</t> | ||||
<vspace blankLines='1' /> | <t> | |||
Within each element of csa_sec_parms, the fore and back RPCSEC_GSS con | ||||
Within each element of csa_sec_parms, the fore and back RPCSEC_GSS con | texts <bcp14>MUST</bcp14> | |||
texts MUST | ||||
share the same GSS context | share the same GSS context | |||
and MUST have the same seq_window | and <bcp14>MUST</bcp14> have the same seq_window | |||
(see Section 5.2.3.1 of <xref target="RFC2203">RFC2203</xref>). | (see Section <xref target="RFC2203" sectionFormat="bare" section="5.2. | |||
3.1"/> | ||||
of RFC 2203 <xref target="RFC2203" format="default"/>). | ||||
The fore and back RPCSEC_GSS context state | The fore and back RPCSEC_GSS context state | |||
are independent of each other as far as the | are independent of each other as far as the | |||
RPCSEC_GSS sequence number (see the seq_num | RPCSEC_GSS sequence number (see the seq_num | |||
field in the rpc_gss_cred_t data type of Sections | field in the rpc_gss_cred_t data type of Sections | |||
5 and 5.3.1 of <xref target="RFC2203" />). | <xref target="RFC2203" sectionFormat="bare" section="5"/> and | |||
<vspace blankLines='1' /> | <xref target="RFC2203" sectionFormat="bare" section="5.3.1"/> of | |||
If an RPCSEC_GSS handle is using the SSV context (see <xref | <xref target="RFC2203" format="default"/>). | |||
target="ssv_mech"/>), then because each SSV RPCSEC_GSS | </t> | |||
<t> | ||||
If an RPCSEC_GSS handle is using the SSV context (see <xref target="ssv_m | ||||
ech" 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 | considerations specific to this situation discussed in <xref target="rpcs | |||
target="rpcsec_ssv_consider"/>. | ec_ssv_consider" format="default"/>. | |||
<vspace blankLines='1' /> | </t> | |||
</dd> | ||||
</t> | </dl> | |||
</list> | <t> | |||
</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 MUST have a sequence | CB_SEQUENCE received on a slot <bcp14>MUST</bcp14> have a sequence | |||
ID equal to 1; if not, the replier MUST 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" numbere | |||
<section toc="exclude" anchor="OP_CREATE_SESSION_IMPLEMENTATION" title="IMPLEM | d="true"> | |||
ENTATION"> | <name>IMPLEMENTATION</name> | |||
<t> | <t> | |||
To describe a possible implementation, the same notation for client | To describe a possible implementation, the same notation for client | |||
records introduced in the description of EXCHANGE_ID is used | records introduced in the description of EXCHANGE_ID is used | |||
with the following addition: | with the following addition: | |||
<list style="empty"> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
clientid_arg: | clientid_arg: | |||
The value of the csa_clientid field of the CREATE_SESSION4args | The value of the csa_clientid field of the CREATE_SESSION4args | |||
structure of the current request. | structure of the current request. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Since CREATE_SESSION is a non-idempotent operation, we | Since CREATE_SESSION is a non-idempotent operation, we | |||
need to consider the possibility that retries may occur | need to consider the possibility that retries may occur | |||
as a result of a client restart, network partition, | as a result of a client restart, network partition, | |||
malfunctioning router, etc. For each client ID | malfunctioning router, etc. For each client ID | |||
created by EXCHANGE_ID, the server maintains a | created by EXCHANGE_ID, the server maintains a | |||
separate reply cache (called the CREATE_SESSION reply cache) | separate reply cache (called the CREATE_SESSION reply cache) | |||
similar to the session reply | similar to the session reply | |||
cache used for SEQUENCE operations, with two | cache used for SEQUENCE operations, with two | |||
distinctions. | distinctions. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
First, this is a reply cache just for | First, this is a reply cache just for | |||
detecting and processing CREATE_SESSION requests for a | detecting and processing CREATE_SESSION requests for a | |||
given client ID. | given client ID. | |||
</t> | </li> | |||
<t> | <li> | |||
Second, the size of the client ID | Second, the size of the client ID | |||
reply cache is of one slot (and as a result, the | reply cache is of one slot (and as a result, the | |||
CREATE_SESSION request does not carry a slot number). | CREATE_SESSION request does not carry a slot number). | |||
This means that at most one CREATE_SESSION request for | This means that at most one CREATE_SESSION request for | |||
a given client ID can be outstanding. | a given client ID can be outstanding. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
As previously stated, CREATE_SESSION can be sent with | As previously stated, CREATE_SESSION can be sent with | |||
or without a preceding SEQUENCE operation. Even if a | or without a preceding SEQUENCE operation. Even if a | |||
SEQUENCE precedes CREATE_SESSION, the server MUST | SEQUENCE precedes CREATE_SESSION, the server <bcp14>MUST</bcp14> | |||
maintain the CREATE_SESSION reply cache, which | maintain the CREATE_SESSION reply cache, which | |||
is separate from the reply cache for the session | is separate from the reply cache for the session | |||
associated with a SEQUENCE. If CREATE_SESSION was | associated with a SEQUENCE. If CREATE_SESSION was | |||
originally sent by itself, the client MAY send | originally sent by itself, the client <bcp14>MAY</bcp14> send | |||
a retry of the CREATE_SESSION operation within a | a retry of the CREATE_SESSION operation within a | |||
COMPOUND preceded by a SEQUENCE. If CREATE_SESSION | COMPOUND preceded by a SEQUENCE. If CREATE_SESSION | |||
was originally sent in a COMPOUND that started with a | was originally sent in a COMPOUND that started with a | |||
SEQUENCE, then the client SHOULD send a retry in | SEQUENCE, then the client <bcp14>SHOULD</bcp14> send a retry in | |||
a COMPOUND that starts with a SEQUENCE that has the | a COMPOUND that starts with a SEQUENCE that has the | |||
same session ID as the SEQUENCE of the original | same session ID as the SEQUENCE of the original | |||
request. However, the client MAY send a retry in a | request. However, the client <bcp14>MAY</bcp14> send a retry in a | |||
COMPOUND that either has no preceding SEQUENCE, or | COMPOUND that either has no preceding SEQUENCE, or | |||
has a preceding SEQUENCE that refers to a different | has a preceding SEQUENCE that refers to a different | |||
session than the original CREATE_SESSION. This might | session than the original CREATE_SESSION. This might | |||
be necessary if the client sends a CREATE_SESSION | be necessary if the client sends a CREATE_SESSION | |||
in a COMPOUND preceded by a SEQUENCE with session | in a COMPOUND preceded by a SEQUENCE with session | |||
ID X, and session X no longer exists. Regardless, any | ID X, and session X no longer exists. Regardless, any | |||
retry of CREATE_SESSION, with or without a preceding | retry of CREATE_SESSION, with or without a preceding | |||
SEQUENCE, MUST use the same value of csa_sequence | SEQUENCE, <bcp14>MUST</bcp14> use the same value of csa_sequence | |||
as the original. | as the original. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
After the client received a reply to an EXCHANGE_ID operation that contain s | After the client received a reply to an EXCHANGE_ID operation that contain s | |||
a new, unconfirmed client ID, | a new, unconfirmed client ID, | |||
the server expects the client to follow | the server expects the client to follow | |||
with a CREATE_SESSION operation to confirm the client ID. The | with a CREATE_SESSION operation to confirm the client ID. The | |||
server expects value of csa_sequenceid in the arguments to | server expects value of csa_sequenceid in the arguments to | |||
that CREATE_SESSION to be | that CREATE_SESSION to be | |||
to equal the value of the field eir_sequenceid that was returned in | to equal the value of the field eir_sequenceid that was returned in | |||
results of the EXCHANGE_ID that returned the unconfirmed | results of the EXCHANGE_ID that returned the unconfirmed | |||
client ID. | client ID. | |||
Before the server replies to that EXCHANGE_ID operation, | Before the server replies to that EXCHANGE_ID operation, | |||
it initializes the client ID slot to be equal | it initializes the client ID slot to be equal | |||
to eir_sequenceid - 1 (accounting for underflow), | to eir_sequenceid - 1 (accounting for underflow), | |||
and records a contrived CREATE_SESSION result | and records a contrived CREATE_SESSION result | |||
with a "cached" result of NFS4ERR_SEQ_MISORDERED. | with a "cached" result of NFS4ERR_SEQ_MISORDERED. | |||
With the client ID slot thus initialized, the processing of the | With the client ID slot thus initialized, the processing of the | |||
CREATE_SESSION operation is divided into four phases: | CREATE_SESSION operation is divided into four phases: | |||
<list style="numbers"> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
Client record look up. The server looks up the client ID | Client record look up. The server looks up the client ID | |||
in its client record table. | in its client record table. | |||
If the server contains no records | If the server contains no records | |||
with client ID equal to clientid_arg, then most | with client ID equal to clientid_arg, then most | |||
likely the client's state has been purged during a | likely the client's state has been purged during a | |||
period of inactivity, possibly due to a loss of | period of inactivity, possibly due to a loss of | |||
connectivity. NFS4ERR_STALE_CLIENTID is returned, | connectivity. NFS4ERR_STALE_CLIENTID is returned, | |||
and no changes are made to any client records on | and no changes are made to any client records on | |||
the server. Otherwise, the server goes to phase 2. | the server. Otherwise, the server goes to phase 2. | |||
</t> | </li> | |||
<t> | <li> | |||
Sequence ID processing. If csa_sequenceid is equal to the | Sequence ID processing. If csa_sequenceid is equal to the | |||
sequence ID in the client ID's slot, then this is a replay | sequence ID in the client ID's slot, then this is a replay | |||
of the previous CREATE_SESSION request, and the server | of the previous CREATE_SESSION request, and the server | |||
returns the cached result. | returns the cached result. | |||
If csa_sequenceid is not equal to the sequence ID in the slot, | If csa_sequenceid is not equal to the sequence ID in the slot, | |||
and is more than one greater (accounting for wraparound), | and is more than one greater (accounting for wraparound), | |||
then the server returns the error NFS4ERR_SEQ_MISORDERED, | then the server returns the error NFS4ERR_SEQ_MISORDERED, | |||
and does not change the slot. If csa_sequenceid is | and does not change the slot. If csa_sequenceid is | |||
equal to the slot's sequence ID + 1 (accounting for | equal to the slot's sequence ID + 1 (accounting for | |||
wraparound), then the slot's sequence ID is set to | wraparound), then the slot's sequence ID is set to | |||
csa_sequenceid, and the CREATE_SESSION processing goes to | csa_sequenceid, and the CREATE_SESSION processing goes to | |||
the next phase. A subsequent new CREATE_SESSION call | the next phase. A subsequent new CREATE_SESSION call | |||
over the same client ID MUST | over the same client ID <bcp14>MUST</bcp14> | |||
use a csa_sequenceid that is one greater than the | use a csa_sequenceid that is one greater than the | |||
sequence ID in the slot. | sequence ID in the slot. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
Client ID confirmation. If this would be the first session for the | Client ID confirmation. If this would be the first session for the | |||
client ID, the CREATE_SESSION operation serves to confirm the | client ID, the CREATE_SESSION operation serves to confirm the | |||
client ID. | client ID. | |||
Otherwise, | Otherwise, | |||
the client ID confirmation phase is skipped and only | the client ID confirmation phase is skipped and only | |||
the session creation phase occurs. | the session creation phase occurs. | |||
Any case in which there is more than one | Any case in which there is more than one | |||
record with identical values for client ID represents | record with identical values for client ID represents | |||
a server implementation error. | a server implementation error. | |||
Operation in the | Operation in the | |||
potential valid cases is summarized as follows. | potential valid cases is summarized as follows. | |||
<list style="symbols"> | </t> | |||
<t>Successful Confirmation | <ul spacing="normal"> | |||
<list style="empty"> | <li> | |||
<t> | <t>Successful Confirmation | |||
</t> | ||||
<ul empty="true" spacing="normal"> | ||||
<li> | ||||
If the server has the following unconfirmed record, then this | If the server has the following unconfirmed record, then this | |||
is the expected confirmation of an unconfirmed record. | is the expected confirmation of an unconfirmed record. | |||
</t> | </li> | |||
<t> | <li> | |||
{ ownerid, verifier, principal_arg, clientid_arg, unconfirmed } | { ownerid, verifier, principal_arg, clientid_arg, unconfirmed } | |||
</t> | </li> | |||
<t> | <li> | |||
As noted in <xref target="OP_EXCHANGE_ID_IMPLEMENTATION" />, | As noted in <xref target="OP_EXCHANGE_ID_IMPLEMENTATION" format="def | |||
ault"/>, | ||||
the server might also have the following confirmed record. | the server might also have the following confirmed record. | |||
</t> | </li> | |||
<t> | <li> | |||
{ ownerid, old_verifier, principal_arg, old_clientid, confirmed } | { ownerid, old_verifier, principal_arg, old_clientid, confirmed } | |||
</t> | </li> | |||
<t> | <li> | |||
The server schedules the replacement of both records with: | The server schedules the replacement of both records with: | |||
</t> | </li> | |||
<t> | <li> | |||
{ ownerid, verifier, principal_arg, clientid_arg, confirmed } | { ownerid, verifier, principal_arg, clientid_arg, confirmed } | |||
</t> | </li> | |||
<t> | <li> | |||
The processing of CREATE_SESSION continues on to session creation. | The processing of CREATE_SESSION continues on to session creation. | |||
Once the session is successfully created, the scheduled client | Once the session is successfully created, the scheduled client | |||
record replacement is committed. If the session is not | record replacement is committed. If the session is not | |||
successfully created, then no changes are made to any client | successfully created, then no changes are made to any client | |||
records on the server. | records on the server. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
<li> | ||||
<t>Unsuccessful Confirmation | <t>Unsuccessful Confirmation | |||
<list style="empty"> | </t> | |||
<t> | <ul empty="true" spacing="normal"> | |||
<li> | ||||
If the server has the following record, then the client has | If the server has the following record, then the client has | |||
changed principals after the previous EXCHANGE_ID request, | changed principals after the previous EXCHANGE_ID request, | |||
or there has been a chance collision between shorthand client | or there has been a chance collision between shorthand client | |||
identifiers. | identifiers. | |||
</t> | </li> | |||
<t> | <li> | |||
{ *, *, old_principal_arg, clientid_arg, * } | { *, *, old_principal_arg, clientid_arg, * } | |||
</t> | </li> | |||
<t> | <li> | |||
Neither of these cases is permissible. Processing stops and | Neither of these cases is permissible. Processing stops and | |||
NFS4ERR_CLID_INUSE is returned to the client. No changes are | NFS4ERR_CLID_INUSE is returned to the client. No changes are | |||
made to any client records on the server. | made to any client records on the server. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
<li> | ||||
<t> | <t> | |||
Session creation. | Session creation. | |||
The server confirmed the client ID, either in this | The server confirmed the client ID, either in this | |||
CREATE_SESSION operation, or a previous CREATE_SESSION | CREATE_SESSION operation, or a previous CREATE_SESSION | |||
operation. | operation. | |||
The server examines the remaining fields of the arguments. | The server examines the remaining fields of the arguments. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
The server creates the session by recording the | The server creates the session by recording the | |||
parameter values used (including whether the | parameter values used (including whether the | |||
CREATE_SESSION4_FLAG_PERSIST flag is set and has | CREATE_SESSION4_FLAG_PERSIST flag is set and has | |||
been accepted by the server) and allocating space | been accepted by the server) and allocating space | |||
for the session reply cache (if there is not enough | for the session reply cache (if there is not enough | |||
space, the server returns NFS4ERR_NOSPC). For each slot in the | space, the server returns NFS4ERR_NOSPC). For each slot in the | |||
reply cache, the server sets the sequence ID to zero, | reply cache, the server sets the sequence ID to zero, | |||
and records an entry containing a COMPOUND | and records an entry containing a COMPOUND | |||
reply with zero operations and the error | reply with zero operations and the error | |||
NFS4ERR_SEQ_MISORDERED. This way, if the first | NFS4ERR_SEQ_MISORDERED. This way, if the first | |||
SEQUENCE request sent has a sequence ID equal to | SEQUENCE request sent has a sequence ID equal to | |||
zero, the server can simply return what is in the | zero, the server can simply return what is in the | |||
reply cache: NFS4ERR_SEQ_MISORDERED. The client | reply cache: NFS4ERR_SEQ_MISORDERED. The client | |||
initializes its reply cache for receiving callbacks | initializes its reply cache for receiving callbacks | |||
in the same way, and similarly, the first CB_SEQUENCE | in the same way, and similarly, the first CB_SEQUENCE | |||
operation on a slot after session creation MUST have | operation on a slot after session creation <bcp14>MUST</bcp14> have | |||
a sequence ID of one. | a sequence ID of one. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
If the session state is created successfully, the server associates | If the session state is created successfully, the server associates | |||
the session with the client ID provided by the client. | the session with the client ID provided by the client. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
When a request that had CREATE_SESSION4_FLAG_CONN_RDMA set | When a request that had CREATE_SESSION4_FLAG_CONN_RDMA set | |||
needs to be retried, the retry | needs to be retried, the retry | |||
MUST be done on a new connection that is in non-RDMA mode. | <bcp14>MUST</bcp14> be done on a new connection that is in non-RDMA mode. | |||
If properties of the new connection are different enough | If properties of the new connection are different enough | |||
that the arguments to CREATE_SESSION need to change, then | that the arguments to CREATE_SESSION need to change, then | |||
a non-retry MUST be sent. The server will eventually dispose | a non-retry <bcp14>MUST</bcp14> be sent. The server will eventually dispo se | |||
of any session that was created on the original connection. | of any session that was created on the original connection. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ol> | |||
<t> | <t> | |||
On the backchannel, the client and server might wish to | On the backchannel, the client and server might wish to | |||
have many slots, in some cases perhaps more that the fore channel, in | have many slots, in some cases perhaps more that the fore channel, in | |||
order to deal with the situations where the | order to deal with the situations where the | |||
network link has high latency and is the primary | network link has high latency and is the primary | |||
bottleneck for response to recalls. If so, and if the | bottleneck for response to recalls. If so, and if the | |||
client provides too few slots to the backchannel, | client provides too few slots to the backchannel, | |||
the server might limit the number of recallable | the server might limit the number of recallable | |||
objects it gives to the client. | objects it gives to the client. | |||
</t> | </t> | |||
<t> | <t> | |||
Implementing RPCSEC_GSS callback support requires | Implementing RPCSEC_GSS callback support requires | |||
changes to both the client and server implementations of | changes to both the client and server implementations of | |||
RPCSEC_GSS. One possible set of changes includes: | RPCSEC_GSS. One possible set of changes includes: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Adding a data structure that wraps the GSS-API | Adding a data structure that wraps the GSS-API | |||
context with a reference count. | context with a reference count. | |||
</t> | </li> | |||
<t> | <li> | |||
New functions to increment and decrement the reference | New functions to increment and decrement the reference | |||
count. If the reference count is decremented to zero, | count. If the reference count is decremented to zero, | |||
the wrapper data structure and the GSS-API context it | the wrapper data structure and the GSS-API context it | |||
refers to would be freed. | refers to would be freed. | |||
</t> | </li> | |||
<t> | <li> | |||
Change RPCSEC_GSS to create the wrapper data | Change RPCSEC_GSS to create the wrapper data | |||
structure upon receiving GSS-API context from | structure upon receiving GSS-API context from | |||
gss_accept_sec_context() and gss_init_sec_context(). | gss_accept_sec_context() and gss_init_sec_context(). | |||
The reference count would be initialized to 1. | The reference count would be initialized to 1. | |||
</t> | </li> | |||
<t> | <li> | |||
Adding a function to map an existing | Adding a function to map an existing | |||
RPCSEC_GSS handle to a pointer to the wrapper data | RPCSEC_GSS handle to a pointer to the wrapper data | |||
structure. The reference count would be incremented. | structure. The reference count would be incremented. | |||
</t> | </li> | |||
<t> | <li> | |||
Adding a function to create a new RPCSEC_GSS | Adding a function to create a new RPCSEC_GSS | |||
handle from a pointer to the wrapper data structure. | handle from a pointer to the wrapper data structure. | |||
The reference count would be incremented. | The reference count would be incremented. | |||
</t> | </li> | |||
<t> | <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. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="OP_DESTROY_SESSION" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 44: DESTROY_SESSION - Destroy a Session</name> | |||
$ --> | <section toc="exclude" anchor="OP_DESTROY_SESSION_ARGUMENT" numbered="tr | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | ue"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENT</name> | |||
<section anchor="OP_DESTROY_SESSION" title="Operation 44: DESTROY_SESSION - Dest | <sourcecode type="xdr"><![CDATA[ | |||
roy a Session" > | ||||
<section toc="exclude" anchor="OP_DESTROY_SESSION_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
struct DESTROY_SESSION4args { | struct DESTROY_SESSION4args { | |||
sessionid4 dsa_sessionid; | sessionid4 dsa_sessionid; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_DESTROY_SESSION_RESULT" numbered="true | |||
</figure> | "> | |||
</section> | <name>RESULT</name> | |||
<section toc="exclude" anchor="OP_DESTROY_SESSION_RESULT" title="RESULT"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
struct DESTROY_SESSION4res { | struct DESTROY_SESSION4res { | |||
nfsstat4 dsr_status; | nfsstat4 dsr_status; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_DESTROY_SESSION_DESCRIPTION" numbered= | |||
</figure> | "true"> | |||
</section> | <name>DESCRIPTION</name> | |||
<section toc="exclude" anchor="OP_DESTROY_SESSION_DESCRIPTION" title="DESCRIPT | <t> | |||
ION"> | ||||
<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 | |||
immediately disassociated. If the connection has no remaining | immediately disassociated. If the connection has no remaining | |||
associated sessions, the connection | associated sessions, the connection | |||
MAY be closed by the server. | <bcp14>MAY</bcp14> be closed by the server. | |||
Locks, delegations, layouts, wants, and the lease, which are all | Locks, delegations, layouts, wants, and the lease, which are all | |||
tied to the client ID, are not affected by DESTROY_SESSION. | tied to the client ID, are not affected by DESTROY_SESSION. | |||
</t> | </t> | |||
<t> | <t> | |||
DESTROY_SESSION MUST be invoked on a connection that | DESTROY_SESSION <bcp14>MUST</bcp14> be invoked on a connection that | |||
is associated with the session being destroyed. | is associated with the session being destroyed. | |||
In addition, if SP4_MACH_CRED state protection | In addition, if SP4_MACH_CRED state protection | |||
was specified when the client ID was created, | was specified when the client ID was created, | |||
the RPCSEC_GSS principal that created the session MUST be | the RPCSEC_GSS principal that created the session <bcp14>MUST</bcp14> be | |||
the one that destroys the session, using RPCSEC_GSS | the one that destroys the session, using RPCSEC_GSS | |||
privacy or integrity. If SP4_SSV state protection was | privacy or integrity. If SP4_SSV state protection was | |||
specified when the client ID was created, RPCSEC_GSS | specified when the client ID was created, RPCSEC_GSS | |||
using the SSV mechanism (<xref target="ssv_mech" />) | using the SSV mechanism (<xref target="ssv_mech" format="default"/>) | |||
MUST be used, with integrity or privacy. | <bcp14>MUST</bcp14> be used, with integrity or privacy. | |||
</t> | </t> | |||
<t> | <t> | |||
If the COMPOUND request starts with SEQUENCE, and | If the COMPOUND request starts with SEQUENCE, and | |||
if the sessionids specified in SEQUENCE and DESTROY_SESSION | if the sessionids specified in SEQUENCE and DESTROY_SESSION | |||
are the same, then | are the same, then | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
DESTROY_SESSION MUST be the final operation in the COMPOUND | <li> | |||
DESTROY_SESSION <bcp14>MUST</bcp14> be the final operation in the COMPOUN | ||||
D | ||||
request. | request. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
It is advisable to avoid placing DESTROY_SESSION in a | It is advisable to avoid placing DESTROY_SESSION in a | |||
COMPOUND request with other state-modifying | COMPOUND request with other state-modifying | |||
operations, because the DESTROY_SESSION will destroy | operations, because the DESTROY_SESSION will destroy | |||
the reply cache. | the reply cache. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
Because the session and its reply cache are destroyed, a client that | Because the session and its reply cache are destroyed, a client that | |||
retries the request may receive an error in | retries the request may receive an error in | |||
reply to the retry, even though the original request was | reply to the retry, even though the original request was | |||
successful. | successful. | |||
</t> | </li> | |||
</ul> | ||||
</list> | <t> | |||
</t> | ||||
<t> | ||||
If the COMPOUND request starts with SEQUENCE, and | If the COMPOUND request starts with SEQUENCE, and | |||
if the sessionids specified in SEQUENCE and DESTROY_SESSION | if the sessionids specified in SEQUENCE and DESTROY_SESSION | |||
are different, then DESTROY_SESSION can appear in any position | are different, then DESTROY_SESSION can appear in any position | |||
of the COMPOUND request (except for the first position). The | of the COMPOUND request (except for the first position). The | |||
two sessionids can belong to different client IDs. | two sessionids can belong to different client IDs. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
If the COMPOUND request does not start with | If the COMPOUND request does not start with | |||
SEQUENCE, and if DESTROY_SESSION is not the | SEQUENCE, and if DESTROY_SESSION is not the | |||
sole operation, then server MUST return | sole operation, then server <bcp14>MUST</bcp14> return | |||
NFS4ERR_NOT_ONLY_OP. | NFS4ERR_NOT_ONLY_OP. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
If there is a backchannel on the session and the | If there is a backchannel on the session and the | |||
server has outstanding CB_COMPOUND operations for the | server has outstanding CB_COMPOUND operations for the | |||
session which have not been replied to, then the server | session which have not been replied to, then the server | |||
MAY refuse to destroy the session and return an error. | <bcp14>MAY</bcp14> refuse to destroy the session and return an error. | |||
If so, then | If so, then | |||
in the event the backchannel is down, the server | in the event the backchannel is down, the server | |||
SHOULD return NFS4ERR_CB_PATH_DOWN to inform the | <bcp14>SHOULD</bcp14> return NFS4ERR_CB_PATH_DOWN to inform the | |||
client that the backchannel needs to be repaired before | client that the backchannel needs to be repaired before | |||
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 SHOULD 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 SHOULD 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> | <section anchor="OP_FREE_STATEID" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 45: FREE_STATEID - Free Stateid with No Locks</name> | |||
$ --> | <section toc="exclude" anchor="OP_FREE_STATEID_ARGUMENT" numbered="true" | |||
<!-- Copyright (C) The IETF Trust (2007) --> | > | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENT</name> | |||
<section anchor="OP_FREE_STATEID" title="Operation 45: FREE_STATEID - Free State | <sourcecode type="xdr"><![CDATA[ | |||
id with No Locks" > | ||||
<section toc="exclude" anchor="OP_FREE_STATEID_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
struct FREE_STATEID4args { | struct FREE_STATEID4args { | |||
stateid4 fsa_stateid; | stateid4 fsa_stateid; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_FREE_STATID_RESULT" numbered="true"> | |||
</figure> | <name>RESULT</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_FREE_STATID_RESULT" title="RESULT"> | ||||
<figure> | ||||
<artwork> | ||||
struct FREE_STATEID4res { | struct FREE_STATEID4res { | |||
nfsstat4 fsr_status; | nfsstat4 fsr_status; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_FREE_STATEID4_DESCRIPTION" numbered="t | |||
</figure> | rue"> | |||
</section> | <name>DESCRIPTION</name> | |||
<section toc="exclude" anchor="OP_FREE_STATEID4_DESCRIPTION" title="DESCRIPTIO | <t> | |||
N"> | ||||
<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 | |||
of server revocation. If there are valid locks (of any kind) | of server revocation. If there are valid locks (of any kind) | |||
associated with the stateid in question, the error NFS4ERR_LOCKS_HELD | associated with the stateid in question, the error NFS4ERR_LOCKS_HELD | |||
will be returned, and the associated stateid will not be freed. | will be returned, and the associated stateid will not be freed. | |||
</t> | </t> | |||
<t> | <t> | |||
When a stateid is freed that had been associated with revoked locks, | When a stateid is freed that had been associated with revoked locks, | |||
by sending the FREE_STATEID operation, the client acknowledges the loss of those | by sending the FREE_STATEID operation, the client acknowledges the loss of those | |||
locks. This allows the server, once all such revoked state is | locks. This allows the server, once all such revoked state is | |||
acknowledged, | acknowledged, | |||
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" />. | the edge conditions discussed in <xref target="server_failure" format="def | |||
</t> | ault"/>. | |||
<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> | |||
<section anchor="OP_GET_DIR_DELEGATION" numbered="true" toc="default"> | ||||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 46: GET_DIR_DELEGATION - Get a Directory Delegation</nam | |||
$ --> | e> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_GET_DIR_DELEGATION_ARGUMENT" numbered= | |||
<!-- Copyright (C) The Internet Society (2006) --> | "true"> | |||
<section anchor="OP_GET_DIR_DELEGATION" title="Operation 46: GET_DIR_DELEGATION | <name>ARGUMENT</name> | |||
- Get a Directory Delegation" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_GET_DIR_DELEGATION_ARGUMENT" title="ARGUMENT | ||||
"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_GET_DIR_DELEGATION_RESULT" numbered="t | |||
</section> | rue"> | |||
<section toc="exclude" anchor="OP_GET_DIR_DELEGATION_RESULT" title="RESULT"> | <name>RESULT</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
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 37316 ¶ | skipping to change at line 37330 ¶ | |||
case GDD4_UNAVAIL: | case GDD4_UNAVAIL: | |||
bool gddrnf_will_signal_deleg_avail; | bool gddrnf_will_signal_deleg_avail; | |||
}; | }; | |||
union GET_DIR_DELEGATION4res | union GET_DIR_DELEGATION4res | |||
switch (nfsstat4 gddr_status) { | switch (nfsstat4 gddr_status) { | |||
case NFS4_OK: | case NFS4_OK: | |||
GET_DIR_DELEGATION4res_non_fatal gddr_res_non_fatal4; | GET_DIR_DELEGATION4res_non_fatal gddr_res_non_fatal4; | |||
default: | default: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_GET_DIR_DELEGATION_DESCRIPTION" number | |||
</figure> | ed="true"> | |||
</section> | <name>DESCRIPTION</name> | |||
<section toc="exclude" anchor="OP_GET_DIR_DELEGATION_DESCRIPTION" title="DESCR | <t> | |||
IPTION"> | ||||
<t> | ||||
The GET_DIR_DELEGATION operation is used by a client to request | The GET_DIR_DELEGATION operation is used by a client to request | |||
a directory delegation. The directory is represented by the | a directory delegation. The directory is represented by the | |||
current filehandle. The client also specifies whether it wants | current filehandle. The client also specifies whether it wants | |||
the server to notify it when the directory changes in certain | the server to notify it when the directory changes in certain | |||
ways by setting one or more bits in a bitmap. The server may | ways by setting one or more bits in a bitmap. The server may | |||
refuse to grant the delegation. In that case, the server | refuse to grant the delegation. In that case, the server | |||
will return NFS4ERR_DIRDELEG_UNAVAIL. If the server decides to | will return NFS4ERR_DIRDELEG_UNAVAIL. If the server decides to | |||
hand out the delegation, it will return a cookie verifier for | hand out the delegation, it will return a cookie verifier for | |||
that directory. If the cookie verifier changes when the client | that directory. If the cookie verifier changes when the client | |||
is holding the delegation, the delegation will be recalled | is holding the delegation, the delegation will be recalled | |||
unless the client has asked for notification for this event. | unless the client has asked for notification for this event. | |||
</t> | </t> | |||
<t> | <t> | |||
The server will also return a directory delegation stateid, | The server will also return a directory delegation stateid, | |||
gddr_stateid, as a result of the | gddr_stateid, as a result of the | |||
GET_DIR_DELEGATION operation. This stateid will appear in | GET_DIR_DELEGATION operation. This stateid will appear in | |||
callback messages related to the delegation, such as | callback messages related to the delegation, such as | |||
notifications and delegation recalls. The client will use this | notifications and delegation recalls. The client will use this | |||
stateid to return the delegation voluntarily or upon recall. A | stateid to return the delegation voluntarily or upon recall. A | |||
delegation is returned by calling the DELEGRETURN operation. | delegation is returned by calling the DELEGRETURN operation. | |||
</t> | </t> | |||
<t> | <t> | |||
The server might not be able to support notifications of certain | The server might not be able to support notifications of certain | |||
events. If the client asks for such notifications, the server | events. If the client asks for such notifications, the server | |||
MUST inform the client of its inability to do so as part of the | <bcp14>MUST</bcp14> inform the client of its inability to do so as part of the | |||
GET_DIR_DELEGATION reply by not setting the appropriate bits in | GET_DIR_DELEGATION reply by not setting the appropriate bits in | |||
the supported notifications bitmask, gddr_notification, contained | the supported notifications bitmask, gddr_notification, contained | |||
in the reply. The server MUST NOT add bits to gddr_notification | in the reply. The server <bcp14>MUST NOT</bcp14> add bits to gddr_notific ation | |||
that the client did not request. | that the client did not request. | |||
</t> | </t> | |||
<t> | <t> | |||
The GET_DIR_DELEGATION operation can be used for both normal and | The GET_DIR_DELEGATION operation can be used for both normal and | |||
named attribute directories. | named attribute directories. | |||
</t> | </t> | |||
<t> | <t> | |||
If client sets gdda_signal_deleg_avail to TRUE, then it is | If client sets gdda_signal_deleg_avail to TRUE, then it is | |||
registering with the client a "want" for a directory | registering with the client a "want" for a directory | |||
delegation. If the delegation is not available, and the server | delegation. If the delegation is not available, and the server | |||
supports and will honor the "want", | supports and will honor the "want", | |||
the results will have gddrnf_will_signal_deleg_avail set to TRUE | the results will have gddrnf_will_signal_deleg_avail set to TRUE | |||
and no error will be indicated on return. | and no error will be indicated on return. | |||
If so, the client should expect a future CB_RECALLABLE_OBJ_AVAIL | If so, the client should expect a future CB_RECALLABLE_OBJ_AVAIL | |||
operation to indicate that a directory delegation is available. | operation to indicate that a directory delegation is available. | |||
If the server does not wish to honor the "want" or is not able | If the server does not wish to honor the "want" or is not able | |||
to do so, it returns the error NFS4ERR_DIRDELEG_UNAVAIL. If the | to do so, it returns the error NFS4ERR_DIRDELEG_UNAVAIL. If the | |||
delegation is immediately available, the server SHOULD return it with | delegation is immediately available, the server <bcp14>SHOULD</bcp14> retu rn it with | |||
the response to the operation, rather than via a callback. | the response to the operation, rather than via a callback. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
When a client makes a request for a | When a client makes a request for a | |||
directory delegation while it already holds | directory delegation while it already holds | |||
a directory delegation for that directory | a directory delegation for that directory | |||
(including the case where it has been | (including the case where it has been | |||
recalled but not yet returned by the client | recalled but not yet returned by the client | |||
or revoked by the server), the server MUST | or revoked by the server), the server <bcp14>MUST</bcp14> | |||
reply with the value of gddr_status set to | reply with the value of gddr_status set to | |||
NFS4_OK, the value of gddrnf_status set to | NFS4_OK, the value of gddrnf_status set to | |||
GDD4_UNAVAIL, and the value of | GDD4_UNAVAIL, and the value of | |||
gddrnf_will_signal_deleg_avail set to | gddrnf_will_signal_deleg_avail set to | |||
FALSE. The delegation the client held | FALSE. The delegation the client held | |||
before the request remains intact, and its | before the request remains intact, and its | |||
state is unchanged. The current stateid is | state is unchanged. The current stateid is | |||
not changed (see <xref | not changed (see <xref target="current_stateid" format="default"/> for a d | |||
target="current_stateid"/> for a description | escription | |||
of the current stateid). | of the current stateid). | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_GET_DIR_DELEGATION_IMPLEMENTATION" title="IM | <section toc="exclude" anchor="OP_GET_DIR_DELEGATION_IMPLEMENTATION" num | |||
PLEMENTATION"> | bered="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
Directory delegations provide the benefit of improving cache | Directory delegations provide the benefit of improving cache | |||
consistency of namespace information. This is done through | consistency of namespace information. This is done through | |||
synchronous callbacks. A server must support synchronous | synchronous callbacks. A server must support synchronous | |||
callbacks in order to support directory delegations. In addition | callbacks in order to support directory delegations. In addition | |||
to that, asynchronous notifications provide a way to reduce | to that, asynchronous notifications provide a way to reduce | |||
network traffic as well as improve client performance in certain | network traffic as well as improve client performance in certain | |||
conditions. | conditions. | |||
</t> | </t> | |||
<t> | <t> | |||
Notifications are specified in terms of potential | Notifications are specified in terms of potential | |||
changes to the directory. A client can ask to be | changes to the directory. A client can ask to be | |||
notified of events by setting one or more | notified of events by setting one or more | |||
bits in gdda_notification_types. | bits in gdda_notification_types. | |||
The client can ask for notifications on addition of entries | The client can ask for notifications on addition of entries | |||
to a directory (by setting the | to a directory (by setting the | |||
NOTIFY4_ADD_ENTRY in gdda_notification_types), | NOTIFY4_ADD_ENTRY in gdda_notification_types), | |||
notifications on entry removal | notifications on entry removal | |||
(NOTIFY4_REMOVE_ENTRY), renames | (NOTIFY4_REMOVE_ENTRY), renames | |||
(NOTIFY4_RENAME_ENTRY), directory attribute | (NOTIFY4_RENAME_ENTRY), directory attribute | |||
changes (NOTIFY4_CHANGE_DIR_ATTRIBUTES), | changes (NOTIFY4_CHANGE_DIR_ATTRIBUTES), | |||
and cookie verifier changes | and cookie verifier changes | |||
(NOTIFY4_CHANGE_COOKIE_VERIFIER) by setting | (NOTIFY4_CHANGE_COOKIE_VERIFIER) by setting | |||
one or more corresponding bits in the | one or more corresponding bits in the | |||
gdda_notification_types field. | gdda_notification_types field. | |||
</t> | </t> | |||
<t> | <t> | |||
The client can also ask for | The client can also ask for | |||
notifications of changes to | notifications of changes to | |||
attributes of directory entries | attributes of directory entries | |||
(NOTIFY4_CHANGE_CHILD_ATTRIBUTES) | (NOTIFY4_CHANGE_CHILD_ATTRIBUTES) | |||
in order to keep its attribute cache up to date. However, any | in order to keep its attribute cache up to date. However, any | |||
changes made to child attributes do not cause the delegation to | changes made to child attributes do not cause the delegation to | |||
be recalled. If a client is interested in directory entry | be recalled. If a client is interested in directory entry | |||
caching or negative name caching, it can set the | caching or negative name caching, it can set the | |||
gdda_notification_types appropriately to its particular need | gdda_notification_types appropriately to its particular need | |||
and the server will notify it of | and the server will notify it of | |||
all changes that would otherwise invalidate its name cache. The | all changes that would otherwise invalidate its name cache. The | |||
kind of notification a client asks for may depend on the | kind of notification a client asks for may depend on the | |||
directory size, its rate of change, and the applications being | directory size, its rate of change, and the applications being | |||
used to access that directory. The enumeration of the conditions under | used to access that directory. The enumeration of the conditions under | |||
which a client might ask for a notification is out of the scope | which a client might ask for a notification is out of the scope | |||
of this specification. | of this specification. | |||
</t> | </t> | |||
<t> | <t> | |||
For attribute notifications, the client | For attribute notifications, the client | |||
will set bits in the gdda_dir_attributes | will set bits in the gdda_dir_attributes | |||
bitmap to indicate which attributes | bitmap to indicate which attributes | |||
it wants to be notified of. If the server does not support | it wants to be notified of. If the server does not support | |||
notifications for changes to a certain attribute, it SHOULD NOT | notifications for changes to a certain attribute, it <bcp14>SHOULD NOT</bc p14> | |||
set that attribute in the supported attribute bitmap | set that attribute in the supported attribute bitmap | |||
specified in the reply (gddr_dir_attributes). The client will | specified in the reply (gddr_dir_attributes). The client will | |||
also set in the gdda_child_attributes bitmap the attributes | also set in the gdda_child_attributes bitmap the attributes | |||
of directory entries it wants to be notified of, and | of directory entries it wants to be notified of, and | |||
the server will indicate in gddr_child_attributes which | the server will indicate in gddr_child_attributes which | |||
attributes of directory entries it will notify the client of. | attributes of directory entries it will notify the client of. | |||
</t> | </t> | |||
<t> | <t> | |||
The client will also let the server know if | The client will also let the server know if | |||
it wants to get the notification as soon as the attribute change | it wants to get the notification as soon as the attribute change | |||
occurs or after a certain delay by setting a delay factor; | occurs or after a certain delay by setting a delay factor; | |||
gdda_child_attr_delay is for attribute changes to directory entries and | gdda_child_attr_delay is for attribute changes to directory entries and | |||
gdda_dir_attr_delay is for attribute changes to the directory. If this | gdda_dir_attr_delay is for attribute changes to the directory. If this | |||
delay factor is set to zero, that indicates to the server that | delay factor is set to zero, that indicates to the server that | |||
the client wants to be notified of any attribute changes as soon | the client wants to be notified of any attribute changes as soon | |||
as they occur. If the delay factor is set to N seconds, the server will | as they occur. If the delay factor is set to N seconds, the server will | |||
make a best-effort guarantee that attribute updates are | make a best-effort guarantee that attribute updates are | |||
synchronized within N seconds. | synchronized within N seconds. | |||
If the client asks | If the client asks | |||
for a delay factor that the server does not support or that may | for a delay factor that the server does not support or that may | |||
cause significant resource consumption on the server by causing | cause significant resource consumption on the server by causing | |||
the server to send a lot of notifications, the server should not | the server to send a lot of notifications, the server should not | |||
commit to sending out notifications for attributes and | commit to sending out notifications for attributes and | |||
therefore must not set the appropriate bit in the | therefore must not set the appropriate bit in the | |||
gddr_child_attributes and gddr_dir_attributes bitmaps in the response. | gddr_child_attributes and gddr_dir_attributes bitmaps in the response. | |||
</t> | </t> | |||
<t> | <t> | |||
The client MUST use a security tuple (<xref | The client <bcp14>MUST</bcp14> use a security tuple (<xref target="NFSv4_S | |||
target="NFSv4_Security_Tuples"/>) that the | ecurity_Tuples" format="default"/>) that the | |||
directory or its applicable ancestor (<xref | directory or its applicable ancestor (<xref target="Security_Service_Negot | |||
target="Security_Service_Negotiation"/>) is | iation" format="default"/>) is | |||
exported with. If not, the server MUST return | exported with. If not, the server <bcp14>MUST</bcp14> return | |||
NFS4ERR_WRONGSEC to the operation that both precedes | NFS4ERR_WRONGSEC to the operation that both precedes | |||
GET_DIR_DELEGATION and sets the current filehandle | GET_DIR_DELEGATION and sets the current filehandle | |||
(see <xref target="using_secinfo"/>). | (see <xref target="using_secinfo" format="default"/>). | |||
</t> | </t> | |||
<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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_GETDEVICEINFO" numbered="true" toc="default"> | |||
$ --> | <name>Operation 47: GETDEVICEINFO - Get Device Information</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_GETDEVICEINFO_ARGUMENT" numbered="true | |||
<!-- Copyright (C) The Internet Society (2006) --> | "> | |||
<section anchor="OP_GETDEVICEINFO" title="Operation 47: GETDEVICEINFO - Get Devi | <name>ARGUMENT</name> | |||
ce Information" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_GETDEVICEINFO_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_GETDEVICEINFO_RESULT" numbered="true"> | |||
</figure> | <name>RESULT</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_GETDEVICEINFO_RESULT" title="RESULT"> | ||||
<figure> | ||||
<artwork> | ||||
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; | |||
default: | default: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_GETDEVICEINFO_DESCRIPTION" numbered="t | |||
</figure> | rue"> | |||
</section> | <name>DESCRIPTION</name> | |||
<section toc="exclude" anchor="OP_GETDEVICEINFO_DESCRIPTION" title="DESCRIPTIO | <t> | |||
N"> | ||||
<t> | ||||
The GETDEVICEINFO operation returns pNFS storage device address | The GETDEVICEINFO operation returns pNFS storage device address | |||
information for the specified device ID. | information for the specified device ID. | |||
The client identifies the device information to be returned by | The client identifies the device information to be returned by | |||
providing the gdia_device_id and gdia_layout_type that uniquely | providing the gdia_device_id and gdia_layout_type that uniquely | |||
identify the device. The client provides gdia_maxcount | identify the device. The client provides gdia_maxcount | |||
to limit the number of bytes for the result. This maximum size | to limit the number of bytes for the result. This maximum size | |||
represents all of the data being returned within the | represents all of the data being returned within the | |||
GETDEVICEINFO4resok structure and includes the XDR overhead. | GETDEVICEINFO4resok structure and includes the XDR overhead. | |||
The server may return less data. If the server is unable to | The server may return less data. If the server is unable to | |||
return any information within the gdia_maxcount limit, the error | return any information within the gdia_maxcount limit, the error | |||
NFS4ERR_TOOSMALL will be returned. However, if gdia_maxcount is | NFS4ERR_TOOSMALL will be returned. However, if gdia_maxcount is | |||
zero, NFS4ERR_TOOSMALL MUST NOT be returned. | zero, NFS4ERR_TOOSMALL <bcp14>MUST NOT</bcp14> be returned. | |||
</t> | </t> | |||
<t> | <t> | |||
The da_layout_type field of the gdir_device_addr returned | The da_layout_type field of the gdir_device_addr returned | |||
by the server MUST be equal to the gdia_layout_type specified | by the server <bcp14>MUST</bcp14> be equal to the gdia_layout_type specifi | |||
by the client. If it is not equal, the client SHOULD ignore | ed | |||
by the client. If it is not equal, the client <bcp14>SHOULD</bcp14> ignor | ||||
e | ||||
the response as invalid and behave as if the server returned | the response as invalid and behave as if the server returned | |||
an error, even if the client does have support for the | an error, even if the client does have support for the | |||
layout type returned. | layout type returned. | |||
</t> | </t> | |||
<t> | <t> | |||
The client also provides a notification bitmap, | The client also provides a notification bitmap, | |||
gdia_notify_types, for the device ID mapping | gdia_notify_types, for the device ID mapping | |||
notification for which it is interested in receiving; | notification for which it is interested in receiving; | |||
the server must support device ID notifications | the server must support device ID notifications | |||
for the notification request to have affect. | for the notification request to have affect. | |||
The notification mask is composed in the same | The notification mask is composed in the same | |||
manner as the bitmap for file attributes (<xref | manner as the bitmap for file attributes (<xref target="fattr4" format="de | |||
target="fattr4" />). The numbers of bit positions | fault"/>). The numbers of bit positions | |||
are listed in the notify_device_type4 enumeration type | are listed in the notify_device_type4 enumeration type | |||
(<xref target="OP_CB_NOTIFY_DEVICEID" />). Only | (<xref target="OP_CB_NOTIFY_DEVICEID" format="default"/>). Only | |||
two enumerated values of notify_device_type4 currently | two enumerated values of notify_device_type4 currently | |||
apply to GETDEVICEINFO: | apply to GETDEVICEINFO: | |||
NOTIFY_DEVICEID4_CHANGE | NOTIFY_DEVICEID4_CHANGE | |||
and NOTIFY_DEVICEID4_DELETE (see <xref | and NOTIFY_DEVICEID4_DELETE (see <xref target="OP_CB_NOTIFY_DEVICEID" form | |||
target="OP_CB_NOTIFY_DEVICEID" />). | at="default"/>). | |||
</t> | </t> | |||
<t> | <t> | |||
The notification bitmap applies only to the specified device ID. | The notification bitmap applies only to the specified device ID. | |||
If a client sends a GETDEVICEINFO operation on a deviceID multiple times, | If a client sends a GETDEVICEINFO operation on a deviceID multiple times, | |||
the last notification bitmap is used by the server for | the last notification bitmap is used by the server for | |||
subsequent notifications. If the bitmap is zero or empty, | subsequent notifications. If the bitmap is zero or empty, | |||
then the device ID's notifications are turned off. | then the device ID's notifications are turned off. | |||
</t> | </t> | |||
<t> | <t> | |||
If the client wants to just update or turn off notifications, | If the client wants to just update or turn off notifications, | |||
it MAY send a GETDEVICEINFO operation with gdia_maxcount set to zero. | it <bcp14>MAY</bcp14> send a GETDEVICEINFO operation with gdia_maxcount set to zero. | |||
In that event, if the device ID is valid, the reply's da_addr_body | In that event, if the device ID is valid, the reply's da_addr_body | |||
field of the gdir_device_addr field will be of zero length. | field of the gdir_device_addr field will be of zero length. | |||
</t> | </t> | |||
<t> | <t> | |||
If an unknown device ID is given in gdia_device_id, | If an unknown device ID is given in gdia_device_id, | |||
the server returns NFS4ERR_NOENT. | the server returns NFS4ERR_NOENT. | |||
Otherwise, the device address | Otherwise, the device address | |||
information is returned in gdir_device_addr. | information is returned in gdir_device_addr. | |||
Finally, if the server supports | Finally, if the server supports | |||
notifications for device ID mappings, the gdir_notification | notifications for device ID mappings, the gdir_notification | |||
result will contain a bitmap of which notifications | result will contain a bitmap of which notifications | |||
it will actually send to the client (via CB_NOTIFY_DEVICEID, | it will actually send to the client (via CB_NOTIFY_DEVICEID, | |||
see <xref target="OP_CB_NOTIFY_DEVICEID" />). | see <xref target="OP_CB_NOTIFY_DEVICEID" format="default"/>). | |||
</t> | </t> | |||
<t> | <t> | |||
If NFS4ERR_TOOSMALL is returned, the results also contain | If NFS4ERR_TOOSMALL is returned, the results also contain | |||
gdir_mincount. The value of gdir_mincount represents the | gdir_mincount. The value of gdir_mincount represents the | |||
minimum size necessary to obtain the device information. | minimum size necessary to obtain the device information. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_GETDEVICEINFO_IMPLEMENTATION" title="IMPLEME | <section toc="exclude" anchor="OP_GETDEVICEINFO_IMPLEMENTATION" numbered | |||
NTATION"> | ="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
Aside from updating or turning off notifications, another | Aside from updating or turning off notifications, another | |||
use case for gdia_maxcount being set to zero is to validate | use case for gdia_maxcount being set to zero is to validate | |||
a device ID. | a device ID. | |||
</t> | </t> | |||
<t> | <t> | |||
The client SHOULD request a notification for changes or | The client <bcp14>SHOULD</bcp14> request a notification for changes or | |||
deletion of a device ID to device address mapping so | deletion of a device ID to device address mapping so | |||
that the server can allow the client gracefully use a | that the server can allow the client gracefully use a | |||
new mapping, without having pending I/O fail abruptly, | new mapping, without having pending I/O fail abruptly, | |||
or force layouts using the device ID to be recalled | or force layouts using the device ID to be recalled | |||
or revoked. | or revoked. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
It is possible that GETDEVICEINFO (and | It is possible that GETDEVICEINFO (and | |||
GETDEVICELIST) will race with CB_NOTIFY_DEVICEID, | GETDEVICELIST) will race with CB_NOTIFY_DEVICEID, | |||
i.e., CB_NOTIFY_DEVICEID arrives before the client | i.e., CB_NOTIFY_DEVICEID arrives before the client | |||
gets and processes the response to GETDEVICEINFO or | gets and processes the response to GETDEVICEINFO or | |||
GETDEVICELIST. The analysis of the race leverages the | GETDEVICELIST. The analysis of the race leverages the | |||
fact that the server MUST NOT delete a device ID that | fact that the server <bcp14>MUST NOT</bcp14> delete a device ID that | |||
is referred to by a layout the client has. | is referred to by a layout the client has. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
CB_NOTIFY_DEVICEID deletes a device ID. | CB_NOTIFY_DEVICEID deletes a device ID. | |||
If the client believes it has layouts that refer to the | If the client believes it has layouts that refer to the | |||
device ID, then it is possible that layouts referring to | device ID, then it is possible that layouts referring to | |||
the deleted device ID have been revoked. | the deleted device ID have been revoked. | |||
The client should send a TEST_STATEID request using the | The client should send a TEST_STATEID request using the | |||
stateid for each layout that might have been revoked. If | stateid for each layout that might have been revoked. If | |||
TEST_STATEID indicates that any layouts have been revoked, the | TEST_STATEID indicates that any layouts have been revoked, the | |||
client must recover from layout revocation as described in | client must recover from layout revocation as described in | |||
<xref | <xref target="revoke_layout" format="default"/>. If TEST_STATEID indicate | |||
target="revoke_layout" />. If TEST_STATEID indicates that at least | s that at least | |||
one layout has not been revoked, the client should send | one layout has not been revoked, the client should send | |||
a GETDEVICEINFO operation on the supposedly deleted | a GETDEVICEINFO operation on the supposedly deleted | |||
device ID to verify that the device ID | device ID to verify that the device ID | |||
has been deleted. | has been deleted. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
If GETDEVICEINFO indicates that the device ID | If GETDEVICEINFO indicates that the device ID | |||
does not exist, then the client assumes the server is faulty | does not exist, then the client assumes the server is faulty | |||
and recovers by sending an EXCHANGE_ID operation. If GETDEVICEINFO | and recovers by sending an EXCHANGE_ID operation. If GETDEVICEINFO | |||
indicates that the device ID does exist, then while the server is | indicates that the device ID does exist, then while the server is | |||
faulty for sending an erroneous device ID deletion notification, | faulty for sending an erroneous device ID deletion notification, | |||
the degree to which it is faulty does not require the client to | the degree to which it is faulty does not require the client to | |||
create a new client ID. | create a new client ID. | |||
<vspace blankLines='1' /> | </t> | |||
<t> | ||||
If the client does not have layouts that refer to the | If the client does not have layouts that refer to the | |||
device ID, no harm is done. | device ID, no harm is done. | |||
The client should mark the device ID as deleted, and when | The client should mark the device ID as deleted, and when | |||
GETDEVICEINFO or GETDEVICELIST results are | GETDEVICEINFO or GETDEVICELIST results are | |||
received that indicate that the device ID has been | received that indicate that the device ID has been | |||
in fact deleted, the device ID should be removed from the | in fact deleted, the device ID should be removed from the | |||
client's cache. | client's cache. | |||
</t> | </t> | |||
</li> | ||||
<t> | <li> | |||
CB_NOTIFY_DEVICEID indicates that a device ID's device | CB_NOTIFY_DEVICEID indicates that a device ID's device | |||
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. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | ||||
</section> | <section anchor="OP_GETDEVICELIST" numbered="true" toc="default"> | |||
</section> | <name>Operation 48: GETDEVICELIST - Get All Device Mappings for a File S | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | ystem</name> | |||
$ --> | <section toc="exclude" anchor="OP_GETDEVICELIST_ARGUMENT" numbered="true | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | "> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENT</name> | |||
<section anchor="OP_GETDEVICELIST" title="Operation 48: GETDEVICELIST - Get All | <sourcecode type="xdr"><![CDATA[ | |||
Device Mappings for a File System" > | ||||
<section toc="exclude" anchor="OP_GETDEVICELIST_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_GETDEVICELIST_RESULT" numbered="true"> | |||
</figure> | <name>RESULT</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_GETDEVICELIST_RESULT" title="RESULT"> | ||||
<figure> | ||||
<artwork> | ||||
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; | |||
default: | default: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_GETDEVICELIST_DESCRIPTION" numbered="t | |||
</figure> | rue"> | |||
</section> | <name>DESCRIPTION</name> | |||
<section toc="exclude" anchor="OP_GETDEVICELIST_DESCRIPTION" title="DESCRIPTIO | <t> | |||
N"> | ||||
<t> | ||||
This operation is used by the client to enumerate all of the | This operation is used by the client to enumerate all of the | |||
device IDs that a server's file system uses. | device IDs that a server's file system uses. | |||
</t> | </t> | |||
<t> | <t> | |||
The client provides a current filehandle of a file object that | The client provides a current filehandle of a file object that | |||
belongs to the file system (i.e., all file objects sharing the same | belongs to the file system (i.e., all file objects sharing the same | |||
fsid as that of the current filehandle) and the layout type | fsid as that of the current filehandle) and the layout type | |||
in gdia_layout_type. Since | in gdia_layout_type. Since | |||
this operation might require multiple calls to enumerate all the | this operation might require multiple calls to enumerate all the | |||
device IDs (and is thus | device IDs (and is thus | |||
similar to the <xref target="OP_READDIR"> | similar to the <xref target="OP_READDIR" format="default"> | |||
READDIR</xref> operation), the client also provides gdia_cookie | READDIR</xref> operation), the client also provides gdia_cookie | |||
and gdia_cookieverf to specify the current cursor position in the | and gdia_cookieverf to specify the current cursor position in the | |||
list. When the client wants to read from the beginning of the | list. When the client wants to read from the beginning of the | |||
file system's device mappings, it sets gdla_cookie to zero. The | file system's device mappings, it sets gdla_cookie to zero. The | |||
field gdla_cookieverf MUST be ignored by the server when | field gdla_cookieverf <bcp14>MUST</bcp14> be ignored by the server when | |||
gdla_cookie is zero. | gdla_cookie is zero. | |||
The client provides gdla_maxdevices to limit the number of device IDs | The client provides gdla_maxdevices to limit the number of device IDs | |||
in the result. If gdla_maxdevices is zero, the server MUST return | in the result. If gdla_maxdevices is zero, the server <bcp14>MUST</bcp14> return | |||
NFS4ERR_INVAL. | NFS4ERR_INVAL. | |||
The server MAY return fewer device IDs. | The server <bcp14>MAY</bcp14> return fewer device IDs. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
The successful response to the operation will contain the | The successful response to the operation will contain the | |||
cookie, gdlr_cookie, and the cookie verifier, gdlr_cookieverf, to be | cookie, gdlr_cookie, and the cookie verifier, gdlr_cookieverf, to be | |||
used on the subsequent GETDEVICELIST. A gdlr_eof value of TRUE | used on the subsequent GETDEVICELIST. A gdlr_eof value of TRUE | |||
signifies that there are no remaining entries in the server's | signifies that there are no remaining entries in the server's | |||
device list. Each element of gdlr_deviceid_list contains | device list. Each element of gdlr_deviceid_list contains | |||
a device ID. | a device ID. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_GETDEVICELIST_IMPLEMENTATION" title="IMPLEME | <section toc="exclude" anchor="OP_GETDEVICELIST_IMPLEMENTATION" numbered | |||
NTATION"> | ="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_LAYOUTCOMMIT" numbered="true" toc="default"> | |||
$ --> | <name>Operation 49: LAYOUTCOMMIT - Commit Writes Made Using a Layout</na | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | me> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <section toc="exclude" anchor="OP_LAYOUTCOMMIT_ARGUMENT" numbered="true" | |||
<section anchor="OP_LAYOUTCOMMIT" title="Operation 49: LAYOUTCOMMIT - Commit Wri | > | |||
tes Made Using a Layout" > | <name>ARGUMENT</name> | |||
<sourcecode type="xdr"><![CDATA[ | ||||
<section toc="exclude" anchor="OP_LAYOUTCOMMIT_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
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 37796 ¶ | skipping to change at line 37785 ¶ | |||
struct LAYOUTCOMMIT4args { | struct LAYOUTCOMMIT4args { | |||
/* CURRENT_FH: file */ | /* CURRENT_FH: file */ | |||
offset4 loca_offset; | offset4 loca_offset; | |||
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> | |||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_LAYOUTCOMMIT_RESULT" numbered="true"> | |||
</section> | <name>RESULT</name> | |||
<section toc="exclude" anchor="OP_LAYOUTCOMMIT_RESULT" title="RESULT"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
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; | |||
}; | }; | |||
union LAYOUTCOMMIT4res switch (nfsstat4 locr_status) { | union LAYOUTCOMMIT4res switch (nfsstat4 locr_status) { | |||
case NFS4_OK: | case NFS4_OK: | |||
LAYOUTCOMMIT4resok locr_resok4; | LAYOUTCOMMIT4resok locr_resok4; | |||
default: | default: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LAYOUTCOMMIT_DESCRIPTION" numbered="tr | |||
</figure> | ue"> | |||
</section> | <name>DESCRIPTION</name> | |||
<section toc="exclude" anchor="OP_LAYOUTCOMMIT_DESCRIPTION" title="DESCRIPTION | <t> | |||
"> | ||||
<t> | ||||
The LAYOUTCOMMIT operation commits changes in the layout represented by th e current | The LAYOUTCOMMIT operation commits changes in the layout represented by th e current | |||
filehandle, client ID (derived from the session ID in the | filehandle, client ID (derived from the session ID in the | |||
preceding SEQUENCE operation), byte-range, and stateid. Since | preceding SEQUENCE operation), byte-range, and stateid. Since | |||
layouts are sub-dividable, a smaller portion of a layout, | layouts are sub-dividable, a smaller portion of a layout, | |||
retrieved via LAYOUTGET, can be committed. The byte-range being | retrieved via LAYOUTGET, can be committed. The byte-range being | |||
committed is specified through the byte-range (loca_offset and | committed is specified through the byte-range (loca_offset and | |||
loca_length). This byte-range MUST overlap with one or more existing layou | loca_length). This byte-range <bcp14>MUST</bcp14> overlap with one or more | |||
ts | existing layouts | |||
previously granted via LAYOUTGET (<xref target="OP_LAYOUTGET"/>), | previously granted via LAYOUTGET (<xref target="OP_LAYOUTGET" format="defa | |||
ult"/>), | ||||
each with an iomode of LAYOUTIOMODE4_RW. In the | each with an iomode of LAYOUTIOMODE4_RW. In the | |||
case where the iomode of any held layout segment is not | case where the iomode of any held layout segment is not | |||
LAYOUTIOMODE4_RW, the server should return the error | LAYOUTIOMODE4_RW, the server should return the error | |||
NFS4ERR_BAD_IOMODE. For the case where the client | NFS4ERR_BAD_IOMODE. For the case where the client | |||
does not hold matching layout segment(s) for the | does not hold matching layout segment(s) for the | |||
defined byte-range, the server should return the error | defined byte-range, the server should return the error | |||
NFS4ERR_BAD_LAYOUT. | NFS4ERR_BAD_LAYOUT. | |||
</t> | </t> | |||
<t> | <t> | |||
The LAYOUTCOMMIT operation indicates that the client has | The LAYOUTCOMMIT operation indicates that the client has | |||
completed writes using a layout obtained by a previous | completed writes using a layout obtained by a previous | |||
LAYOUTGET. The client may have only written a subset of the | LAYOUTGET. The client may have only written a subset of the | |||
data range it previously requested. LAYOUTCOMMIT allows it to | data range it previously requested. LAYOUTCOMMIT allows it to | |||
commit or discard provisionally allocated space and to update | commit or discard provisionally allocated space and to update | |||
the server with a new end-of-file. The layout referenced by | the server with a new end-of-file. The layout referenced by | |||
LAYOUTCOMMIT is still valid after the operation completes and | LAYOUTCOMMIT is still valid after the operation completes and | |||
can be continued to be referenced by the client ID, filehandle, | can be continued to be referenced by the client ID, filehandle, | |||
byte-range, layout type, and stateid. | byte-range, layout type, and stateid. | |||
</t> | </t> | |||
<t> | <t> | |||
If the loca_reclaim field is set to TRUE, this indicates that | If the loca_reclaim field is set to TRUE, this indicates that | |||
the client is attempting to commit changes to a layout after the | the client is attempting to commit changes to a layout after the | |||
restart of the metadata server during the metadata server's | restart of the metadata server during the metadata server's | |||
recovery grace period (see <xref target="mds_recovery"/>). This type of r equest may be necessary | recovery grace period (see <xref target="mds_recovery" format="default"/>) . This type of request may be necessary | |||
when the client has uncommitted writes to provisionally | when the client has uncommitted writes to provisionally | |||
allocated byte-ranges of a file that were sent to the storage | allocated byte-ranges of a file that were sent to the storage | |||
devices before the restart of the metadata server. In this case, | devices before the restart of the metadata server. In this case, | |||
the layout provided by the client MUST be a subset of a writable | the layout provided by the client <bcp14>MUST</bcp14> be a subset of a wri table | |||
layout that the client held immediately before the restart of the | layout that the client held immediately before the restart of the | |||
metadata server. The value of the field loca_stateid MUST | metadata server. The value of the field loca_stateid <bcp14>MUST</bcp14> | |||
be a value that the metadata server returned before it restarted. | be a value that the metadata server returned before it restarted. | |||
The metadata server is free to accept or | The metadata server is free to accept or | |||
reject this request based on its own internal metadata | reject this request based on its own internal metadata | |||
consistency checks. If the metadata server finds that the | consistency checks. If the metadata server finds that the | |||
layout provided by the client does not pass its consistency | layout provided by the client does not pass its consistency | |||
checks, it MUST reject the request with the status | checks, it <bcp14>MUST</bcp14> reject the request with the status | |||
NFS4ERR_RECLAIM_BAD. The successful completion of the | NFS4ERR_RECLAIM_BAD. The successful completion of the | |||
LAYOUTCOMMIT request with loca_reclaim set to TRUE does NOT | LAYOUTCOMMIT request with loca_reclaim set to TRUE does NOT | |||
provide the client with a layout for the file. It simply | provide the client with a layout for the file. It simply | |||
commits the changes to the layout specified in the | commits the changes to the layout specified in the | |||
loca_layoutupdate field. To obtain a layout for the file, the | loca_layoutupdate field. To obtain a layout for the file, the | |||
client must send a LAYOUTGET request to the server after the | client must send a LAYOUTGET request to the server after the | |||
server's grace period has expired. If the metadata server | server's grace period has expired. If the metadata server | |||
receives a LAYOUTCOMMIT request with loca_reclaim set to TRUE | receives a LAYOUTCOMMIT request with loca_reclaim set to TRUE | |||
when the metadata server is not in its recovery grace period, it | when the metadata server is not in its recovery grace period, it | |||
MUST reject the request with the status NFS4ERR_NO_GRACE. | <bcp14>MUST</bcp14> reject the request with the status NFS4ERR_NO_GRACE. | |||
</t> | </t> | |||
<t> | <t> | |||
Setting the loca_reclaim field to TRUE is required if and only | Setting the loca_reclaim field to TRUE is required if and only | |||
if the committed layout was acquired before the metadata server | if the committed layout was acquired before the metadata server | |||
restart. If the client is committing a layout that was acquired | restart. If the client is committing a layout that was acquired | |||
during the metadata server's grace period, it MUST set the | during the metadata server's grace period, it <bcp14>MUST</bcp14> set the | |||
"reclaim" field to FALSE. | "reclaim" field to FALSE. | |||
</t> | </t> | |||
<t> | <t> | |||
The loca_stateid is a layout stateid value as | The loca_stateid is a layout stateid value as | |||
returned by previously successful layout operations | returned by previously successful layout operations | |||
(see <xref target="layout_stateid"/>). | (see <xref target="layout_stateid" format="default"/>). | |||
</t> | </t> | |||
<t> | <t> | |||
The loca_last_write_offset field specifies the offset of the | The loca_last_write_offset field specifies the offset of the | |||
last byte written by the client previous to the LAYOUTCOMMIT. | last byte written by the client previous to the LAYOUTCOMMIT. | |||
Note that this value is never equal to the file's size (at most | Note that this value is never equal to the file's size (at most | |||
it is one byte less than the file's size) and MUST be less than | it is one byte less than the file's size) and <bcp14>MUST</bcp14> be less | |||
or equal to NFS4_MAXFILEOFF. Also, loca_last_write_offset MUST | than | |||
or equal to NFS4_MAXFILEOFF. Also, loca_last_write_offset <bcp14>MUST</bc | ||||
p14> | ||||
overlap the range described by loca_offset and loca_length. | overlap the range described by loca_offset and loca_length. | |||
The metadata server | The metadata server | |||
may use this information to determine whether the file's size | may use this information to determine whether the file's size | |||
needs to be updated. If the metadata server updates the file's | needs to be updated. If the metadata server updates the file's | |||
size as the result of the LAYOUTCOMMIT operation, it must return | size as the result of the LAYOUTCOMMIT operation, it must return | |||
the new size (locr_newsize.ns_size) as part of the results. | the new size (locr_newsize.ns_size) as part of the results. | |||
</t> | </t> | |||
<t> | <t> | |||
The loca_time_modify field | The loca_time_modify field | |||
allows the client to suggest a modification time it would like the metadat a | allows the client to suggest a modification time it would like the metadat a | |||
server to set. The metadata server may use the suggestion or | server to set. The metadata server may use the suggestion or | |||
it may use the time of the LAYOUTCOMMIT operation to set the modification | it may use the time of the LAYOUTCOMMIT operation to set the modification | |||
time. If the metadata server uses the client-provided | time. If the metadata server uses the client-provided | |||
modification time, it should ensure that time does not flow backwards. If the | modification time, it should ensure that time does not flow backwards. If the | |||
client wants to force the metadata server to set an exact time, | client wants to force the metadata server to set an exact time, | |||
the client should use a SETATTR operation in a COMPOUND right | the client should use a SETATTR operation in a COMPOUND right | |||
after LAYOUTCOMMIT. See <xref target="committing_layout" /> for | after LAYOUTCOMMIT. See <xref target="committing_layout" format="default" /> for | |||
more details. If the client desires the resultant modification time, | more details. If the client desires the resultant modification time, | |||
it should construct the COMPOUND so that a GETATTR | it should construct the COMPOUND so that a GETATTR | |||
follows the LAYOUTCOMMIT. | follows the LAYOUTCOMMIT. | |||
</t> | </t> | |||
<t> | <t> | |||
The loca_layoutupdate argument to LAYOUTCOMMIT provides a mechanism | The loca_layoutupdate argument to LAYOUTCOMMIT provides a mechanism | |||
for a client to provide layout-specific updates to the metadata | for a client to provide layout-specific updates to the metadata | |||
server. For example, the layout update can describe what byte-ranges | server. For example, the layout update can describe what byte-ranges | |||
of the original layout have been used and what byte-ranges can be | of the original layout have been used and what byte-ranges can be | |||
deallocated. There is no NFSv4.1 file layout-specific layoutupdate4 | deallocated. There is no NFSv4.1 file layout-specific layoutupdate4 | |||
structure. | structure. | |||
</t> | </t> | |||
<t> | <t> | |||
The layout information is more verbose for block devices than for | The layout information is more verbose for block devices than for | |||
objects and files because the latter two hide the details of block | objects and files because the latter two hide the details of block | |||
allocation behind their storage protocols. At the minimum, the | allocation behind their storage protocols. At the minimum, the | |||
client needs to communicate changes to the end-of-file location back | client needs to communicate changes to the end-of-file location back | |||
to the server, and, if desired, its view of the file's modification | to the server, and, if desired, its view of the file's modification | |||
time. For block/volume layouts, it needs to specify precisely | time. For block/volume layouts, it needs to specify precisely | |||
which blocks have been used. | which blocks have been used. | |||
</t> | </t> | |||
<t> | <t> | |||
If the layout identified in the arguments does not exist, the | If the layout identified in the arguments does not exist, the | |||
error NFS4ERR_BADLAYOUT is returned. The layout being committed | error NFS4ERR_BADLAYOUT is returned. The layout being committed | |||
may also be rejected if it does not correspond to an existing | may also be rejected if it does not correspond to an existing | |||
layout with an iomode of LAYOUTIOMODE4_RW. | layout with an iomode of LAYOUTIOMODE4_RW. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value and the | On success, the current filehandle retains its value and the | |||
current stateid retains its value. | current stateid retains its value. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_LAYOUTCOMMIT_IMPLEMENTATION" title="IMPLEMEN | <section toc="exclude" anchor="OP_LAYOUTCOMMIT_IMPLEMENTATION" numbered= | |||
TATION"> | "true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
The client MAY also use LAYOUTCOMMIT with the | <t> | |||
The client <bcp14>MAY</bcp14> also use LAYOUTCOMMIT with the | ||||
loca_reclaim field set to TRUE to convey hints to modified file | loca_reclaim field set to TRUE to convey hints to modified file | |||
attributes or to report layout-type specific information such as | attributes or to report layout-type specific information such as | |||
I/O errors for object-based storage layouts, as normally done | I/O errors for object-based storage layouts, as normally done | |||
during normal operation. Doing so may help the metadata server | during normal operation. Doing so may help the metadata server | |||
to recover files more efficiently after restart. For example, | to recover files more efficiently after restart. For example, | |||
some file system implementations may require expansive recovery | some file system implementations may require expansive recovery | |||
of file system objects if the metadata server does not get a | of file system objects if the metadata server does not get a | |||
positive indication from all clients holding a LAYOUTIOMODE4_RW layout tha t | positive indication from all clients holding a LAYOUTIOMODE4_RW layout tha t | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_LAYOUTGET" numbered="true" toc="default"> | |||
$ --> | <name>Operation 50: LAYOUTGET - Get Layout Information</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_LAYOUTGET_ARGUMENT" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENT</name> | |||
<section anchor="OP_LAYOUTGET" title="Operation 50: LAYOUTGET - Get Layout Infor | <sourcecode type="xdr"><![CDATA[ | |||
mation" > | ||||
<section toc="exclude" anchor="OP_LAYOUTGET_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_LAYOUTGET_RESULT" numbered="true"> | |||
</section> | <name>RESULT</name> | |||
<section toc="exclude" anchor="OP_LAYOUTGET_RESULT" title="RESULT"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
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: | |||
bool logr_will_signal_layout_avail; | bool logr_will_signal_layout_avail; | |||
default: | default: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LAYOUTGET_DESCRIPTION" numbered="true" | |||
</figure> | > | |||
</section> | <name>DESCRIPTION</name> | |||
<section toc="exclude" anchor="OP_LAYOUTGET_DESCRIPTION" title="DESCRIPTION"> | <t> | |||
<t> | ||||
The LAYOUTGET operation requests a layout from the metadata server for rea ding or | The LAYOUTGET operation requests a layout from the metadata server for rea ding or | |||
writing the file given by the filehandle at the | writing the file given by the filehandle at the | |||
byte-range specified by offset and length. Layouts are | byte-range specified by offset and length. Layouts are | |||
identified by the client ID (derived from the session ID in the | identified by the client ID (derived from the session ID in the | |||
preceding SEQUENCE operation), current filehandle, layout type | preceding SEQUENCE operation), current filehandle, layout type | |||
(loga_layout_type), and the layout stateid (loga_stateid). The | (loga_layout_type), and the layout stateid (loga_stateid). The | |||
use of the loga_iomode field depends upon the layout type, but should | use of the loga_iomode field depends upon the layout type, but should | |||
reflect the client's data access intent. | reflect the client's data access intent. | |||
</t> | </t> | |||
<t> | <t> | |||
If the metadata server is in a grace period, and does not | If the metadata server is in a grace period, and does not | |||
persist layouts and device ID to device address mappings, then | persist layouts and device ID to device address mappings, then | |||
it MUST return NFS4ERR_GRACE (see <xref target="reclaim_locks"/>). | it <bcp14>MUST</bcp14> return NFS4ERR_GRACE (see <xref target="reclaim_loc | |||
</t> | ks" format="default"/>). | |||
</t> | ||||
<t> | <t> | |||
The LAYOUTGET operation returns layout information | The LAYOUTGET operation returns layout information | |||
for the specified byte-range: a layout. | for the specified byte-range: a layout. | |||
The client actually specifies two ranges, both starting | The client actually specifies two ranges, both starting | |||
at the offset in the loga_offset field. The first | at the offset in the loga_offset field. The first | |||
range is between loga_offset and loga_offset + loga_length - 1 | range is between loga_offset and loga_offset + loga_length - 1 | |||
inclusive. This range indicates the desired range the client | inclusive. This range indicates the desired range the client | |||
wants the layout to cover. The second range is between | wants the layout to cover. The second range is between | |||
loga_offset and loga_offset + loga_minlength - 1 inclusive. This | loga_offset and loga_offset + loga_minlength - 1 inclusive. This | |||
range indicates the required range the client needs the layout | range indicates the required range the client needs the layout | |||
to cover. Thus, loga_minlength MUST be less than or equal to | to cover. Thus, loga_minlength <bcp14>MUST</bcp14> be less than or equal t o | |||
loga_length. | loga_length. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
When a length field is set to NFS4_UINT64_MAX, | When a length field is set to NFS4_UINT64_MAX, | |||
this indicates a desire (when loga_length is NFS4_UINT64_MAX) | this indicates a desire (when loga_length is NFS4_UINT64_MAX) | |||
or requirement (when loga_minlength is NFS4_UINT64_MAX) | or requirement (when loga_minlength is NFS4_UINT64_MAX) | |||
to get a layout from loga_offset through the | to get a layout from loga_offset through the | |||
end-of-file, regardless of the file's length. | end-of-file, regardless of the file's length. | |||
</t> | </t> | |||
<t> | <t> | |||
The following rules govern the relationships among, | The following rules govern the relationships among, | |||
and the minima of, | and the minima of, | |||
loga_length, loga_minlength, and loga_offset. | loga_length, loga_minlength, and loga_offset. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If loga_length is less than loga_minlength, the metadata server | If loga_length is less than loga_minlength, the metadata server | |||
MUST return NFS4ERR_INVAL. | <bcp14>MUST</bcp14> return NFS4ERR_INVAL. | |||
</t> | </li> | |||
<t> | <li> | |||
If loga_minlength is zero, this is an indication | If loga_minlength is zero, this is an indication | |||
to the metadata server that the client desires any layout | to the metadata server that the client desires any layout | |||
at offset loga_offset or less that the metadata server has | at offset loga_offset or less that the metadata server has | |||
"readily available". Readily is subjective, and depends on | "readily available". Readily is subjective, and depends on | |||
the layout type and the pNFS server implementation. For example, | the layout type and the pNFS server implementation. For example, | |||
some metadata servers might have to pre-allocate stable | some metadata servers might have to pre-allocate stable | |||
storage when they receive a request for a range of a | storage when they receive a request for a range of a | |||
file that goes beyond the file's current length. | file that goes beyond the file's current length. | |||
If loga_minlength is zero and | If loga_minlength is zero and | |||
loga_length is greater than zero, this tells the | loga_length is greater than zero, this tells the | |||
metadata server what range of the layout the client would | metadata server what range of the layout the client would | |||
prefer to have. If loga_length and loga_minlength | prefer to have. If loga_length and loga_minlength | |||
are both zero, then the client is indicating that it desires | are both zero, then the client is indicating that it desires | |||
a layout of any length with the ending offset of the range | a layout of any length with the ending offset of the range | |||
no less than the value specified loga_offset, and the starting offset at or | no less than the value specified loga_offset, and the starting offset at or | |||
below loga_offset. If the metadata server does not have | below loga_offset. If the metadata server does not have | |||
a layout that is readily available, then it MUST return | a layout that is readily available, then it <bcp14>MUST</bcp14> return | |||
NFS4ERR_LAYOUTTRYLATER. | NFS4ERR_LAYOUTTRYLATER. | |||
</t> | </li> | |||
<t> | <li> | |||
If the sum of loga_offset and loga_minlength exceeds | If the sum of loga_offset and loga_minlength exceeds | |||
NFS4_UINT64_MAX, and loga_minlength is not NFS4_UINT64_MAX, | NFS4_UINT64_MAX, and loga_minlength is not NFS4_UINT64_MAX, | |||
the error NFS4ERR_INVAL MUST result. | the error NFS4ERR_INVAL <bcp14>MUST</bcp14> result. | |||
</t> | </li> | |||
<t> | <li> | |||
If the sum of loga_offset and loga_length exceeds | If the sum of loga_offset and loga_length exceeds | |||
NFS4_UINT64_MAX, and loga_length is not NFS4_UINT64_MAX, | NFS4_UINT64_MAX, and loga_length is not NFS4_UINT64_MAX, | |||
the error NFS4ERR_INVAL MUST result. | the error NFS4ERR_INVAL <bcp14>MUST</bcp14> result. | |||
</t> | </li> | |||
</list> | </ul> | |||
<t> | ||||
After the metadata server has performed the above checks on loga_offset, | After the metadata server has performed the above checks on loga_offset, | |||
loga_minlength, and loga_offset, the metadata server MUST return a | loga_minlength, and loga_offset, the metadata server <bcp14>MUST</bcp14> r | |||
layout according to the rules in <xref target="layout_hell"/>. | eturn a | |||
</t> | layout according to the rules in <xref target="layout_hell" format="defaul | |||
<texttable anchor='layout_hell'> | t"/>. | |||
</t> | ||||
<preamble> | <t> | |||
Acceptable layouts based on loga_minlength. | Acceptable layouts based on loga_minlength. | |||
Note: u64m = NFS4_UINT64_MAX; a_off = loga_offset; | Note: u64m = NFS4_UINT64_MAX; a_off = loga_offset; | |||
a_minlen = loga_minlength. | a_minlen = loga_minlength. | |||
</preamble> | </t> | |||
<table anchor="layout_hell" align="center"> | ||||
<ttcol>Layout iomode of request</ttcol> | <thead> | |||
<ttcol>Layout a_minlen of request</ttcol> | <tr> | |||
<ttcol>Layout iomode of reply</ttcol> | <th align="left">Layout iomode of request</th> | |||
<ttcol>Layout offset of reply</ttcol> | <th align="left">Layout a_minlen of request</th> | |||
<ttcol>Layout length of reply</ttcol> | <th align="left">Layout iomode of reply</th> | |||
<th align="left">Layout offset of reply</th> | ||||
<c>_READ</c> | <th align="left">Layout length of reply</th> | |||
<c>u64m</c> | </tr> | |||
<c>MAY be _READ</c> | </thead> | |||
<c>MUST be <= a_off</c> | <tbody> | |||
<c>MUST be >= file length - layout offset</c> | <tr> | |||
<td align="left">_READ</td> | ||||
<c>_READ</c> | <td align="left">u64m</td> | |||
<c>u64m</c> | <td align="left"><bcp14>MAY</bcp14> be _READ</td> | |||
<c>MAY be _RW</c> | <td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | |||
<c>MUST be <= a_off</c> | <td align="left"><bcp14>MUST</bcp14> be >= file length - layo | |||
<c>MUST be u64m</c> | ut offset</td> | |||
</tr> | ||||
<c>_READ</c> | <tr> | |||
<c>> 0 and < u64m</c> | <td align="left">_READ</td> | |||
<c>MAY be _READ</c> | <td align="left">u64m</td> | |||
<c>MUST be <= a_off</c> | <td align="left"><bcp14>MAY</bcp14> be _RW</td> | |||
<c>MUST be >= MIN(file length, a_minlen + a_off) - layout offset</c> | <td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | |||
<td align="left"><bcp14>MUST</bcp14> be u64m</td> | ||||
<c>_READ</c> | </tr> | |||
<c>> 0 and < u64m</c> | <tr> | |||
<c>MAY be _RW</c> | <td align="left">_READ</td> | |||
<c>MUST be <= a_off</c> | <td align="left">> 0 and < u64m</td> | |||
<c>MUST be >= a_off - layout offset + a_minlen</c> | <td align="left"><bcp14>MAY</bcp14> be _READ</td> | |||
<td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | ||||
<c>_READ</c> | <td align="left"><bcp14>MUST</bcp14> be >= MIN(file length, a | |||
<c>0</c> | _minlen + a_off) - layout offset</td> | |||
<c>MAY be _READ</c> | </tr> | |||
<c>MUST be <= a_off</c> | <tr> | |||
<c>MUST be > 0</c> | <td align="left">_READ</td> | |||
<td align="left">> 0 and < u64m</td> | ||||
<c>_READ</c> | <td align="left"><bcp14>MAY</bcp14> be _RW</td> | |||
<c>0</c> | <td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | |||
<c>MAY be _RW</c> | <td align="left"><bcp14>MUST</bcp14> be >= a_off - layout off | |||
<c>MUST be <= a_off</c> | set + a_minlen</td> | |||
<c>MUST be > 0</c> | </tr> | |||
<tr> | ||||
<c>_RW</c> | <td align="left">_READ</td> | |||
<c>u64m</c> | <td align="left">0</td> | |||
<c>MUST be _RW</c> | <td align="left"><bcp14>MAY</bcp14> be _READ</td> | |||
<c>MUST be <= a_off</c> | <td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | |||
<c>MUST be u64m</c> | <td align="left"><bcp14>MUST</bcp14> be > 0</td> | |||
</tr> | ||||
<c>_RW</c> | <tr> | |||
<c>> 0 and < u64m</c> | <td align="left">_READ</td> | |||
<c>MUST be _RW</c> | <td align="left">0</td> | |||
<c>MUST be <= a_off</c> | <td align="left"><bcp14>MAY</bcp14> be _RW</td> | |||
<c>MUST be >= a_off - layout offset + a_minlen</c> | <td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | |||
<td align="left"><bcp14>MUST</bcp14> be > 0</td> | ||||
<c>_RW</c> | </tr> | |||
<c>0</c> | <tr> | |||
<c>MUST be _RW</c> | <td align="left">_RW</td> | |||
<c>MUST be <= a_off</c> | <td align="left">u64m</td> | |||
<c>MUST be > 0</c> | <td align="left"><bcp14>MUST</bcp14> be _RW</td> | |||
<td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | ||||
</texttable> | <td align="left"><bcp14>MUST</bcp14> be u64m</td> | |||
<t> | </tr> | |||
<tr> | ||||
<td align="left">_RW</td> | ||||
<td align="left">> 0 and < u64m</td> | ||||
<td align="left"><bcp14>MUST</bcp14> be _RW</td> | ||||
<td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | ||||
<td align="left"><bcp14>MUST</bcp14> be >= a_off - layout off | ||||
set + a_minlen</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">_RW</td> | ||||
<td align="left">0</td> | ||||
<td align="left"><bcp14>MUST</bcp14> be _RW</td> | ||||
<td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | ||||
<td align="left"><bcp14>MUST</bcp14> be > 0</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
<t> | ||||
If loga_minlength is not zero and the metadata server cannot return a layou t according | If loga_minlength is not zero and the metadata server cannot return a layou t according | |||
to the rules in <xref target="layout_hell"/>, | to the rules in <xref target="layout_hell" format="default"/>, | |||
then the metadata server MUST return the error | then the metadata server <bcp14>MUST</bcp14> return the error | |||
NFS4ERR_BADLAYOUT. If loga_minlength is zero and the metadata server | NFS4ERR_BADLAYOUT. If loga_minlength is zero and the metadata server | |||
cannot or will not return a layout according | cannot or will not return a layout according | |||
to the rules in <xref target="layout_hell"/>, | to the rules in <xref target="layout_hell" format="default"/>, | |||
then the metadata server MUST return the error | then the metadata server <bcp14>MUST</bcp14> return the error | |||
NFS4ERR_LAYOUTTRYLATER. | NFS4ERR_LAYOUTTRYLATER. | |||
Assuming that loga_length is greater | Assuming that loga_length is greater | |||
than loga_minlength or equal to zero, the metadata server SHOULD | than loga_minlength or equal to zero, the metadata server <bcp14>SHOULD</bc | |||
return a layout according to the rules in <xref | p14> | |||
target="layout_hell2"/>. | return a layout according to the rules in <xref target="layout_hell2" forma | |||
</t> | t="default"/>. | |||
</t> | ||||
<texttable anchor='layout_hell2'> | <t> | |||
<preamble> | ||||
Desired layouts based on loga_length. | Desired layouts based on loga_length. | |||
The rules of <xref target='layout_hell'/> MUST be applied first. | The rules of <xref target="layout_hell" format="default"/> <bcp14>MUST</bc p14> be applied first. | |||
Note: u64m = NFS4_UINT64_MAX; a_off = loga_offset; | Note: u64m = NFS4_UINT64_MAX; a_off = loga_offset; | |||
a_len = loga_length. | a_len = loga_length. | |||
</preamble> | </t> | |||
<table anchor="layout_hell2" align="center"> | ||||
<ttcol>Layout iomode of request</ttcol> | <thead> | |||
<ttcol>Layout a_len of request</ttcol> | <tr> | |||
<ttcol>Layout iomode of reply</ttcol> | <th align="left">Layout iomode of request</th> | |||
<ttcol>Layout offset of reply</ttcol> | <th align="left">Layout a_len of request</th> | |||
<ttcol>Layout length of reply</ttcol> | <th align="left">Layout iomode of reply</th> | |||
<th align="left">Layout offset of reply</th> | ||||
<c>_READ</c> | <th align="left">Layout length of reply</th> | |||
<c>u64m</c> | </tr> | |||
<c>MAY be _READ</c> | </thead> | |||
<c>MUST be <= a_off</c> | <tbody> | |||
<c>SHOULD be u64m</c> | <tr> | |||
<td align="left">_READ</td> | ||||
<c>_READ</c> | <td align="left">u64m</td> | |||
<c>u64m</c> | <td align="left"><bcp14>MAY</bcp14> be _READ</td> | |||
<c>MAY be _RW</c> | <td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | |||
<c>MUST be <= a_off</c> | <td align="left"><bcp14>SHOULD</bcp14> be u64m</td> | |||
<c>SHOULD be u64m</c> | </tr> | |||
<tr> | ||||
<c>_READ</c> | <td align="left">_READ</td> | |||
<c>> 0 and < u64m</c> | <td align="left">u64m</td> | |||
<c>MAY be _READ</c> | <td align="left"><bcp14>MAY</bcp14> be _RW</td> | |||
<c>MUST be <= a_off</c> | <td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | |||
<c>SHOULD be >= a_off - layout offset + a_len</c> | <td align="left"><bcp14>SHOULD</bcp14> be u64m</td> | |||
</tr> | ||||
<c>_READ</c> | <tr> | |||
<c>> 0 and < u64m</c> | <td align="left">_READ</td> | |||
<c>MAY be _RW</c> | <td align="left">> 0 and < u64m</td> | |||
<c>MUST be <= a_off</c> | <td align="left"><bcp14>MAY</bcp14> be _READ</td> | |||
<c>SHOULD be >= a_off - layout offset + a_len</c> | <td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | |||
<td align="left"><bcp14>SHOULD</bcp14> be >= a_off - layout o | ||||
<c>_READ</c> | ffset + a_len</td> | |||
<c>0</c> | </tr> | |||
<c>MAY be _READ</c> | <tr> | |||
<c>MUST be <= a_off</c> | <td align="left">_READ</td> | |||
<c>SHOULD be > a_off - layout offset</c> | <td align="left">> 0 and < u64m</td> | |||
<td align="left"><bcp14>MAY</bcp14> be _RW</td> | ||||
<c>_READ</c> | <td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | |||
<c>0</c> | <td align="left"><bcp14>SHOULD</bcp14> be >= a_off - layout o | |||
<c>MAY be _READ</c> | ffset + a_len</td> | |||
<c>MUST be <= a_off</c> | </tr> | |||
<c>SHOULD be > a_off - layout offset</c> | <tr> | |||
<td align="left">_READ</td> | ||||
<c>_RW</c> | <td align="left">0</td> | |||
<c>u64m</c> | <td align="left"><bcp14>MAY</bcp14> be _READ</td> | |||
<c>MUST be _RW</c> | <td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | |||
<c>MUST be <= a_off</c> | <td align="left"><bcp14>SHOULD</bcp14> be > a_off - layout of | |||
<c>SHOULD be u64m</c> | fset</td> | |||
</tr> | ||||
<c>_RW</c> | <tr> | |||
<c>> 0 and < u64m</c> | <td align="left">_READ</td> | |||
<c>MUST be _RW</c> | <td align="left">0</td> | |||
<c>MUST be <= a_off</c> | <td align="left"><bcp14>MAY</bcp14> be _READ</td> | |||
<c>SHOULD be >= a_off - layout offset + a_len</c> | <td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | |||
<td align="left"><bcp14>SHOULD</bcp14> be > a_off - layout of | ||||
<c>_RW</c> | fset</td> | |||
<c>0</c> | </tr> | |||
<c>MUST be _RW</c> | <tr> | |||
<c>MUST be <= a_off</c> | <td align="left">_RW</td> | |||
<c>SHOULD be > a_off - layout offset</c> | <td align="left">u64m</td> | |||
</texttable> | <td align="left"><bcp14>MUST</bcp14> be _RW</td> | |||
<td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | ||||
<t> | <td align="left"><bcp14>SHOULD</bcp14> be u64m</td> | |||
</tr> | ||||
<tr> | ||||
<td align="left">_RW</td> | ||||
<td align="left">> 0 and < u64m</td> | ||||
<td align="left"><bcp14>MUST</bcp14> be _RW</td> | ||||
<td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | ||||
<td align="left"><bcp14>SHOULD</bcp14> be >= a_off - layout o | ||||
ffset + a_len</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">_RW</td> | ||||
<td align="left">0</td> | ||||
<td align="left"><bcp14>MUST</bcp14> be _RW</td> | ||||
<td align="left"><bcp14>MUST</bcp14> be <= a_off</td> | ||||
<td align="left"><bcp14>SHOULD</bcp14> be > a_off - layout of | ||||
fset</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
<t> | ||||
The loga_stateid field specifies a valid stateid. | The loga_stateid field specifies a valid stateid. | |||
If a layout is not currently held by the client, | If a layout is not currently held by the client, | |||
the loga_stateid field represents a stateid | the loga_stateid field represents a stateid | |||
reflecting the correspondingly valid open, | reflecting the correspondingly valid open, | |||
byte-range lock, or delegation stateid. Once a | byte-range lock, or delegation stateid. Once a | |||
layout is held on the file by the client, the | layout is held on the file by the client, the | |||
loga_stateid field MUST be a stateid as returned from | loga_stateid field <bcp14>MUST</bcp14> be a stateid as returned from | |||
a previous LAYOUTGET or LAYOUTRETURN operation or | a previous LAYOUTGET or LAYOUTRETURN operation or | |||
provided by a CB_LAYOUTRECALL operation (see <xref | provided by a CB_LAYOUTRECALL operation (see <xref target="layout_stateid" | |||
target="layout_stateid"/>). | format="default"/>). | |||
</t> | </t> | |||
<t> | <t> | |||
The loga_maxcount field specifies the maximum layout size (in bytes) | The loga_maxcount field specifies the maximum layout size (in bytes) | |||
that the client can handle. If the size of the layout structure | that the client can handle. If the size of the layout structure | |||
exceeds the size specified by maxcount, the metadata server will | exceeds the size specified by maxcount, the metadata server will | |||
return the NFS4ERR_TOOSMALL error. | return the NFS4ERR_TOOSMALL error. | |||
</t> | </t> | |||
<t> | <t> | |||
The returned layout is expressed as an array, | The returned layout is expressed as an array, | |||
logr_layout, with each element of type layout4. If a | logr_layout, with each element of type layout4. If a | |||
file has a single striping pattern, then logr_layout | file has a single striping pattern, then logr_layout | |||
SHOULD contain just one entry. Otherwise, if the | <bcp14>SHOULD</bcp14> contain just one entry. Otherwise, if the | |||
requested range overlaps more than one striping | requested range overlaps more than one striping | |||
pattern, logr_layout will contain the required number | pattern, logr_layout will contain the required number | |||
of entries. The elements of logr_layout MUST be sorted | of entries. The elements of logr_layout <bcp14>MUST</bcp14> be sorted | |||
in ascending order of the value of the lo_offset field | in ascending order of the value of the lo_offset field | |||
of each element. There MUST be no gaps or overlaps | of each element. There <bcp14>MUST</bcp14> be no gaps or overlaps | |||
in the range between two successive elements of | in the range between two successive elements of | |||
logr_layout. The lo_iomode field in each element of | logr_layout. The lo_iomode field in each element of | |||
logr_layout MUST be the same. | logr_layout <bcp14>MUST</bcp14> be the same. | |||
</t> | </t> | |||
<t> | ||||
<t> | <xref target="layout_hell" format="default"/> | |||
<xref target="layout_hell" /> | ||||
and | and | |||
<xref target="layout_hell2" /> | <xref target="layout_hell2" format="default"/> | |||
both refer to a returned layout iomode, offset, and length. | both refer to a returned layout iomode, offset, and length. | |||
Because the returned layout is encoded in the logr_layout array, | Because the returned layout is encoded in the logr_layout array, | |||
more description is required. | more description is required. | |||
<list style='hanging'> | </t> | |||
<dl newline="false" spacing="normal"> | ||||
<t hangText='iomode'/> | <dt>iomode</dt> | |||
<t> | <dd> | |||
The value of the returned layout iomode listed in | The value of the returned layout iomode listed in | |||
<xref target="layout_hell" /> | <xref target="layout_hell" format="default"/> | |||
and | and | |||
<xref target="layout_hell2" /> | <xref target="layout_hell2" format="default"/> | |||
is equal to the value of the lo_iomode field in each | is equal to the value of the lo_iomode field in each | |||
element of logr_layout. | element of logr_layout. | |||
As shown in <xref target="layout_hell" /> | As shown in <xref target="layout_hell" format="default"/> | |||
and <xref target="layout_hell2" />, | and <xref target="layout_hell2" format="default"/>, | |||
the metadata server MAY return a layout with an lo_iomode | the metadata server <bcp14>MAY</bcp14> return a layout with an lo_iomode | |||
different from the requested iomode (field loga_iomode of the request). | different from the requested iomode (field loga_iomode of the request). | |||
If it does so, it MUST | If it does so, it <bcp14>MUST</bcp14> | |||
ensure that the lo_iomode is more permissive than the | ensure that the lo_iomode is more permissive than the | |||
loga_iomode requested. For example, this behavior allows an | loga_iomode requested. For example, this behavior allows an | |||
implementation to upgrade LAYOUTIOMODE4_READ requests to LAYOUTIOMODE4_RW | implementation to upgrade LAYOUTIOMODE4_READ requests to LAYOUTIOMODE4_RW | |||
requests at its discretion, within the limits of the layout type | requests at its discretion, within the limits of the layout type | |||
specific protocol. A lo_iomode of either LAYOUTIOMODE4_READ or | specific protocol. A lo_iomode of either LAYOUTIOMODE4_READ or | |||
LAYOUTIOMODE4_RW MUST be returned. | LAYOUTIOMODE4_RW <bcp14>MUST</bcp14> be returned. | |||
</t> | ||||
<t hangText='offset'/> | </dd> | |||
<t> | <dt>offset</dt> | |||
<dd> | ||||
The value of the returned layout offset listed in | The value of the returned layout offset listed in | |||
<xref target="layout_hell" /> | <xref target="layout_hell" format="default"/> | |||
and | and | |||
<xref target="layout_hell2" /> | <xref target="layout_hell2" format="default"/> | |||
is always equal to the lo_offset field of the first | is always equal to the lo_offset field of the first | |||
element logr_layout. | element logr_layout. | |||
</t> | </dd> | |||
<dt>length</dt> | ||||
<t hangText='length'/> | <dd> | |||
<t> | <t> | |||
When setting the value of the returned layout | When setting the value of the returned layout | |||
length, the situation is complicated by the | length, the situation is complicated by the | |||
possibility that the special layout length value | possibility that the special layout length value | |||
NFS4_UINT64_MAX is involved. For a logr_layout | NFS4_UINT64_MAX is involved. For a logr_layout | |||
array of N elements, the lo_length field in the | array of N elements, the lo_length field in the | |||
first N-1 elements MUST NOT be NFS4_UINT64_MAX. The | first N-1 elements <bcp14>MUST NOT</bcp14> be NFS4_UINT64_MAX. The | |||
lo_length field of the last element of logr_layout | lo_length field of the last element of logr_layout | |||
can be NFS4_UINT64_MAX under some conditions as | can be NFS4_UINT64_MAX under some conditions as | |||
described in the following list. | described in the following list. | |||
<list style='symbols'> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <li> | |||
If an applicable rule of <xref target="layout_hell"/> | If an applicable rule of <xref target="layout_hell" format="default"/> | |||
states that the metadata server MUST return a layout of length | states that the metadata server <bcp14>MUST</bcp14> return a layout of le | |||
ngth | ||||
NFS4_UINT64_MAX, then the lo_length field of the last | NFS4_UINT64_MAX, then the lo_length field of the last | |||
element of logr_layout MUST be NFS4_UINT64_MAX. | element of logr_layout <bcp14>MUST</bcp14> be NFS4_UINT64_MAX. | |||
</t> | </li> | |||
<t> | <li> | |||
If an applicable rule of <xref target="layout_hell"/> | If an applicable rule of <xref target="layout_hell" format="default"/> | |||
states that the metadata server MUST NOT return a layout of length | states that the metadata server <bcp14>MUST NOT</bcp14> return a layout o | |||
f length | ||||
NFS4_UINT64_MAX, then the lo_length field of the last | NFS4_UINT64_MAX, then the lo_length field of the last | |||
element of logr_layout MUST NOT be NFS4_UINT64_MAX. | element of logr_layout <bcp14>MUST NOT</bcp14> be NFS4_UINT64_MAX. | |||
</t> | </li> | |||
<t> | <li> | |||
If an applicable rule of <xref target="layout_hell2"/> | If an applicable rule of <xref target="layout_hell2" format="default"/> | |||
states that the metadata server SHOULD return a layout of length | states that the metadata server <bcp14>SHOULD</bcp14> return a layout of | |||
length | ||||
NFS4_UINT64_MAX, then the lo_length field of the last | NFS4_UINT64_MAX, then the lo_length field of the last | |||
element of logr_layout SHOULD be NFS4_UINT64_MAX. | element of logr_layout <bcp14>SHOULD</bcp14> be NFS4_UINT64_MAX. | |||
</t> | </li> | |||
<t> | <li> | |||
When the value of the returned layout length of | When the value of the returned layout length of | |||
<xref target="layout_hell" /> | <xref target="layout_hell" format="default"/> | |||
and | and | |||
<xref target="layout_hell2" /> is not NFS4_UINT64_MAX, then | <xref target="layout_hell2" format="default"/> is not NFS4_UINT64_MAX, th en | |||
the returned layout length is equal to the sum of the | the returned layout length is equal to the sum of the | |||
lo_length fields of each element of logr_layout. | lo_length fields of each element of logr_layout. | |||
</t> | </li> | |||
</ul> | ||||
</list> | </dd> | |||
</dl> | ||||
</t> | <t> | |||
</list> | ||||
</t> | ||||
<t> | ||||
The logr_return_on_close result field is a directive to return | The logr_return_on_close result field is a directive to return | |||
the layout before closing the file. When the metadata server sets this | the layout before closing the file. When the metadata server sets this | |||
return value to TRUE, it MUST be prepared to recall the layout | return value to TRUE, it <bcp14>MUST</bcp14> be prepared to recall the lay out | |||
in the case in which the client fails to return the layout before close. | in the case in which the client fails to return the layout before close. | |||
For the metadata server that knows a layout must be returned before a | For the metadata server that knows a layout must be returned before a | |||
close of the file, this return value can be used to communicate | close of the file, this return value can be used to communicate | |||
the desired behavior to the client and thus remove one extra | the desired behavior to the client and thus remove one extra | |||
step from the client's and metadata server's interaction. | step from the client's and metadata server's interaction. | |||
</t> | </t> | |||
<t> | <t> | |||
The logr_stateid stateid is returned to | The logr_stateid stateid is returned to | |||
the client for use in subsequent layout related operations. See Sections | the client for use in subsequent layout related operations. See Sections | |||
<xref target="stateid" format="counter" />, <xref target="layout_stateid" | <xref target="stateid" format="counter"/>, <xref target="layout_stateid" f | |||
format="counter" />, and | ormat="counter"/>, and | |||
<xref target="pnfs_operation_sequencing" format="counter" /> for a further | <xref target="pnfs_operation_sequencing" format="counter"/> for a further | |||
discussion and requirements. | discussion and requirements. | |||
</t> | </t> | |||
<t> | <t> | |||
The format of the returned layout (lo_content) | The format of the returned layout (lo_content) | |||
is specific to the layout type. | is specific to the layout type. | |||
The value of the layout type (lo_content.loc_type) for each of | The value of the layout type (lo_content.loc_type) for each of | |||
the elements of the array of layouts returned by the metadata server | the elements of the array of layouts returned by the metadata server | |||
(logr_layout) MUST be equal to the loga_layout_type specified | (logr_layout) <bcp14>MUST</bcp14> be equal to the loga_layout_type specifi | |||
by the client. If it is not equal, the client SHOULD ignore | ed | |||
by the client. If it is not equal, the client <bcp14>SHOULD</bcp14> ignor | ||||
e | ||||
the response as invalid and behave as if the metadata server returned | the response as invalid and behave as if the metadata server returned | |||
an error, even if the client does have support for the | an error, even if the client does have support for the | |||
layout type returned. | layout type returned. | |||
</t> | </t> | |||
<t> | <t> | |||
If neither the requested file nor its | If neither the requested file nor its | |||
containing file system support layouts, the metadata server MUST return | containing file system support layouts, the metadata server <bcp14>MUST</b cp14> return | |||
NFS4ERR_LAYOUTUNAVAILABLE. If the layout type is not supported, | NFS4ERR_LAYOUTUNAVAILABLE. If the layout type is not supported, | |||
the metadata server MUST return NFS4ERR_UNKNOWN_LAYOUTTYPE. | the metadata server <bcp14>MUST</bcp14> return NFS4ERR_UNKNOWN_LAYOUTTYPE. | |||
If layouts are supported but no layout matches the client | If layouts are supported but no layout matches the client | |||
provided layout identification, the metadata server MUST return | provided layout identification, the metadata server <bcp14>MUST</bcp14> re turn | |||
NFS4ERR_BADLAYOUT. If an invalid loga_iomode is specified, or a | NFS4ERR_BADLAYOUT. If an invalid loga_iomode is specified, or a | |||
loga_iomode of LAYOUTIOMODE4_ANY is specified, the metadata server MUST | loga_iomode of LAYOUTIOMODE4_ANY is specified, the metadata server <bcp14> MUST</bcp14> | |||
return NFS4ERR_BADIOMODE. | return NFS4ERR_BADIOMODE. | |||
</t> | </t> | |||
<t> | <t> | |||
If the layout for the file is unavailable due to transient | If the layout for the file is unavailable due to transient | |||
conditions, e.g., file sharing prohibits layouts, the metadata server MUST | conditions, e.g., file sharing prohibits layouts, the metadata server <bcp 14>MUST</bcp14> | |||
return NFS4ERR_LAYOUTTRYLATER. | return NFS4ERR_LAYOUTTRYLATER. | |||
</t> | </t> | |||
<t> | <t> | |||
If the layout request is rejected due to an overlapping layout | If the layout request is rejected due to an overlapping layout | |||
recall, the metadata server MUST return NFS4ERR_RECALLCONFLICT. See <xref | recall, the metadata server <bcp14>MUST</bcp14> return NFS4ERR_RECALLCONFL | |||
target="pnfs_operation_sequencing"/> for details. | ICT. See <xref target="pnfs_operation_sequencing" format="default"/> for detail | |||
</t> | s. | |||
<t> | </t> | |||
<t> | ||||
If the layout conflicts with a mandatory byte-range lock held on the | If the layout conflicts with a mandatory byte-range lock held on the | |||
file, and if the storage devices have no method of enforcing | file, and if the storage devices have no method of enforcing | |||
mandatory locks, other than through the restriction of layouts, the | mandatory locks, other than through the restriction of layouts, the | |||
metadata server SHOULD return NFS4ERR_LOCKED. | metadata server <bcp14>SHOULD</bcp14> return NFS4ERR_LOCKED. | |||
</t> | </t> | |||
<t> | <t> | |||
If client sets loga_signal_layout_avail to TRUE, then it is | If client sets loga_signal_layout_avail to TRUE, then it is | |||
registering with the client a "want" for a layout in the event | registering with the client a "want" for a layout in the event | |||
the layout cannot be obtained due to resource exhaustion. | the layout cannot be obtained due to resource exhaustion. | |||
If the metadata server supports and will honor the "want", | If the metadata server supports and will honor the "want", | |||
the results will have logr_will_signal_layout_avail | the results will have logr_will_signal_layout_avail | |||
set to TRUE. | set to TRUE. | |||
If so, the client should expect a CB_RECALLABLE_OBJ_AVAIL | If so, the client should expect a CB_RECALLABLE_OBJ_AVAIL | |||
operation to indicate that a layout is available. | operation to indicate that a layout is available. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value and the | On success, the current filehandle retains its value and the | |||
current stateid is updated to match the value as returned in the | current stateid is updated to match the value as returned in the | |||
results. | results. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_LAYOUTGET_IMPLEMENTATION" title="IMPLEMENTAT | <section toc="exclude" anchor="OP_LAYOUTGET_IMPLEMENTATION" numbered="tr | |||
ION"> | ue"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
Typically, LAYOUTGET will be called as part of a | Typically, LAYOUTGET will be called as part of a | |||
COMPOUND request after an OPEN operation and results | COMPOUND request after an OPEN operation and results | |||
in the client having location information for the | in the client having location information for the | |||
file. This requires that loga_stateid be set to the | file. This requires that loga_stateid be set to the | |||
special stateid that tells the metadata server to use the | special stateid that tells the metadata server to use the | |||
current stateid, which is set by OPEN (see <xref | current stateid, which is set by OPEN (see <xref target="current_stateid" | |||
target="current_stateid"/>). A client may also hold | format="default"/>). A client may also hold | |||
a layout across multiple OPENs. The client specifies | a layout across multiple OPENs. The client specifies | |||
a layout type that limits what kind of layout the | a layout type that limits what kind of layout the | |||
metadata server will return. This prevents metadata servers from | metadata server will return. This prevents metadata servers from | |||
granting layouts that are unusable by the client. | granting layouts that are unusable by the client. | |||
</t> | </t> | |||
<t> | <t> | |||
As indicated by <xref target="layout_hell" /> and | As indicated by <xref target="layout_hell" format="default"/> and | |||
<xref target="layout_hell2" />, the specification of | <xref target="layout_hell2" format="default"/>, the specification of | |||
LAYOUTGET allows a pNFS client and server considerable | LAYOUTGET allows a pNFS client and server considerable | |||
flexibility. | flexibility. | |||
A pNFS client can take several strategies for sending | A pNFS client can take several strategies for sending | |||
LAYOUTGET. Some examples are as follows. | LAYOUTGET. Some examples are as follows. | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If LAYOUTGET is preceded by OPEN in the same | If LAYOUTGET is preceded by OPEN in the same | |||
COMPOUND request and the OPEN requests OPEN4_SHARE_ACCESS_READ access, | COMPOUND request and the OPEN requests OPEN4_SHARE_ACCESS_READ access, | |||
the client might opt to request a _READ layout | the client might opt to request a _READ layout | |||
with loga_offset set to zero, loga_minlength set to | with loga_offset set to zero, loga_minlength set to | |||
zero, and loga_length set to NFS4_UINT64_MAX. If | zero, and loga_length set to NFS4_UINT64_MAX. If | |||
the file has space allocated to it, that space is | the file has space allocated to it, that space is | |||
striped over one or more storage devices, and there | striped over one or more storage devices, and there | |||
is either no conflicting layout or the concept of | is either no conflicting layout or the concept of | |||
a conflicting layout does not apply to the pNFS | a conflicting layout does not apply to the pNFS | |||
server's layout type or implementation, then the | server's layout type or implementation, then the | |||
metadata server might return a layout with a starting offset | metadata server might return a layout with a starting offset | |||
of zero, and a length equal to the length of the | of zero, and a length equal to the length of the | |||
file, if not NFS4_UINT64_MAX. If the length of the | file, if not NFS4_UINT64_MAX. If the length of the | |||
file is not a multiple of the | file is not a multiple of the | |||
pNFS server's stripe | pNFS server's stripe | |||
width (see <xref target="file_layout_definitions"/> | width (see <xref target="file_layout_definitions" format="default"/> | |||
for a formal definition), the metadata server might round up | for a formal definition), the metadata server might round up | |||
the returned layout's length. | the returned layout's length. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
If LAYOUTGET is preceded by OPEN in the same | If LAYOUTGET is preceded by OPEN in the same | |||
COMPOUND request, and the OPEN requests OPEN4_SHARE_ACCESS_WRITE access a nd does | COMPOUND request, and the OPEN requests OPEN4_SHARE_ACCESS_WRITE access a nd does | |||
not truncate the file, the client might | not truncate the file, the client might | |||
opt to request a _RW layout with loga_offset set | opt to request a _RW layout with loga_offset set | |||
to zero, loga_minlength set to zero, and loga_length | to zero, loga_minlength set to zero, and loga_length | |||
set to the file's current length (if known), or | set to the file's current length (if known), or | |||
NFS4_UINT64_MAX. As with the previous case, under | NFS4_UINT64_MAX. As with the previous case, under | |||
some conditions the metadata server might return a layout | some conditions the metadata server might return a layout | |||
that covers the entire length of the file or beyond. | that covers the entire length of the file or beyond. | |||
</t> | </li> | |||
<t> | <li> | |||
This strategy is as above, but the OPEN truncates the file. In this case, | This strategy is as above, but the OPEN truncates the file. In this case, | |||
the client might anticipate it will be writing to the | the client might anticipate it will be writing to the | |||
file from offset zero, and so loga_offset and loga_minlength | file from offset zero, and so loga_offset and loga_minlength | |||
are set to zero, and loga_length is set to the value of | are set to zero, and loga_length is set to the value of | |||
threshold4_write_iosize. The metadata server might return a layout | threshold4_write_iosize. The metadata server might return a layout | |||
from offset zero with a length at least as long as | from offset zero with a length at least as long as | |||
threshold4_write_iosize. | threshold4_write_iosize. | |||
</t> | </li> | |||
<t> | <li> | |||
A process on the client invokes a request to read | A process on the client invokes a request to read | |||
from offset 10000 for length 50000. The client | from offset 10000 for length 50000. The client | |||
is using buffered I/O, and has buffer sizes of | is using buffered I/O, and has buffer sizes of | |||
4096 bytes. The client intends to map the request | 4096 bytes. The client intends to map the request | |||
of the process into a series of READ requests | of the process into a series of READ requests | |||
starting at offset 8192. The end offset needs to be higher | starting at offset 8192. The end offset needs to be higher | |||
than 10000 + 50000 = 60000, and the next offset that is | than 10000 + 50000 = 60000, and the next offset that is | |||
a multiple of 4096 is 61440. The difference between 61440 and | a multiple of 4096 is 61440. The difference between 61440 and | |||
that starting offset of the layout is 53248 (which is | that starting offset of the layout is 53248 (which is | |||
the product of 4096 and 15). | the product of 4096 and 15). | |||
skipping to change at line 38561 ¶ | skipping to change at line 38554 ¶ | |||
53248, and loga_length set to the file's length | 53248, and loga_length set to the file's length | |||
(if known) minus 8192 or NFS4_UINT64_MAX (if the | (if known) minus 8192 or NFS4_UINT64_MAX (if the | |||
file's length is not known). Since this LAYOUTGET | file's length is not known). Since this LAYOUTGET | |||
request exceeds the metadata server's threshold, it grants | request exceeds the metadata server's threshold, it grants | |||
the layout, possibly with an initial offset of | the layout, possibly with an initial offset of | |||
zero, with an end offset of at least 8192 + 53248 - | zero, with an end offset of at least 8192 + 53248 - | |||
1 = 61439, but preferably a layout with an offset | 1 = 61439, but preferably a layout with an offset | |||
aligned on the stripe width and a length that is | aligned on the stripe width and a length that is | |||
a multiple of the stripe width. | a multiple of the stripe width. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
This strategy is as above, but the client is not using buffered I/O, and | This strategy is as above, but the client is not using buffered I/O, and | |||
instead all internal I/O requests are sent directly to | instead all internal I/O requests are sent directly to | |||
the server. The LAYOUTGET request has loga_offset equal to | the server. The LAYOUTGET request has loga_offset equal to | |||
10000 and loga_minlength set to 50000. The value of loga_length | 10000 and loga_minlength set to 50000. The value of loga_length | |||
is set to the length of the file. The metadata server is free to | is set to the length of the file. The metadata server is free to | |||
return a layout that fully overlaps the requested range, with | return a layout that fully overlaps the requested range, with | |||
a starting offset and length aligned on the stripe width. | a starting offset and length aligned on the stripe width. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
Again, a process on the client invokes a request | Again, a process on the client invokes a request | |||
to read from offset 10000 for length 50000 (i.e. a | to read from offset 10000 for length 50000 (i.e. a | |||
range with a starting offset of 10000 and an ending | range with a starting offset of 10000 and an ending | |||
offset of 69999), and | offset of 69999), and | |||
buffered I/O is in use. The client is expecting | buffered I/O is in use. The client is expecting | |||
that the server might not be able to return the | that the server might not be able to return the | |||
layout for the full I/O range. | layout for the full I/O range. | |||
The client intends to map the request of the | The client intends to map the request of the | |||
process into a series of thirteen READ requests starting at | process into a series of thirteen READ requests starting at | |||
skipping to change at line 38605 ¶ | skipping to change at line 38596 ¶ | |||
and loga_length set to 53248 or higher. The server | and loga_length set to 53248 or higher. The server | |||
will grant a layout possibly with an initial offset | will grant a layout possibly with an initial offset | |||
of zero, with an end offset of at least 8192 + 4096 - | of zero, with an end offset of at least 8192 + 4096 - | |||
1 = 12287, but preferably a layout with an offset | 1 = 12287, but preferably a layout with an offset | |||
aligned on the stripe width and a length that is a | aligned on the stripe width and a length that is a | |||
multiple of the stripe width. This will allow the | multiple of the stripe width. This will allow the | |||
client to make forward progress, possibly | client to make forward progress, possibly | |||
sending more LAYOUTGET operations for the remainder | sending more LAYOUTGET operations for the remainder | |||
of the range. | of the range. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
An NFS client detects a sequential read pattern, | An NFS client detects a sequential read pattern, | |||
and so sends a LAYOUTGET operation that goes well beyond any | and so sends a LAYOUTGET operation that goes well beyond any | |||
current or pending read requests to the server. The | current or pending read requests to the server. The | |||
server might likewise detect this pattern, and | server might likewise detect this pattern, and | |||
grant the LAYOUTGET request. Once the client | grant the LAYOUTGET request. Once the client | |||
reads from an offset of the file that represents | reads from an offset of the file that represents | |||
50% of the way through the range of the last layout | 50% of the way through the range of the last layout | |||
it received, in order to avoid stalling I/O that would wait | it received, in order to avoid stalling I/O that would wait | |||
for a layout, the client sends more operations | for a layout, the client sends more operations | |||
from an offset of the file that represents 50% | from an offset of the file that represents 50% | |||
of the way through the last layout it received. The client | of the way through the last layout it received. The client | |||
continues to request layouts with byte-ranges that are | continues to request layouts with byte-ranges that are | |||
well in advance of the byte-ranges of | well in advance of the byte-ranges of | |||
recent and/or read requests of processes running on the client. | recent and/or read requests of processes running on the client. | |||
</t> | </li> | |||
<t> | <li> | |||
This strategy is as above, but the client fails to detect the | This strategy is as above, but the client fails to detect the | |||
pattern, but the server does. The next time the | pattern, but the server does. The next time the | |||
metadata server gets a LAYOUTGET, it returns a layout with | metadata server gets a LAYOUTGET, it returns a layout with | |||
a length that is well beyond loga_minlength. | a length that is well beyond loga_minlength. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
A client is using buffered I/O, and has a long | A client is using buffered I/O, and has a long | |||
queue of write-behinds to process and also detects | queue of write-behinds to process and also detects | |||
a sequential write pattern. It sends a LAYOUTGET | a sequential write pattern. It sends a LAYOUTGET | |||
for a layout that spans the range of the queued | for a layout that spans the range of the queued | |||
write-behinds and well beyond, including ranges | write-behinds and well beyond, including ranges | |||
beyond the filer's current length. The client | beyond the filer's current length. The client | |||
continues to send LAYOUTGET operations once the write-behind | continues to send LAYOUTGET operations once the write-behind | |||
queue reaches 50% of the maximum queue length. | queue reaches 50% of the maximum queue length. | |||
</t> | </li> | |||
</ul> | ||||
</list> | <t> | |||
</t> | ||||
<t> | ||||
Once the client has obtained a layout referring to a | Once the client has obtained a layout referring to a | |||
particular device ID, the metadata server MUST NOT | particular device ID, the metadata server <bcp14>MUST NOT</bcp14> | |||
delete the device ID until the layout is returned | delete the device ID until the layout is returned | |||
or revoked. | or revoked. | |||
</t> | </t> | |||
<t> | <t> | |||
CB_NOTIFY_DEVICEID can race with LAYOUTGET. One race | CB_NOTIFY_DEVICEID can race with LAYOUTGET. One race | |||
scenario is that LAYOUTGET returns a device ID for which the | scenario is that LAYOUTGET returns a device ID for which the | |||
client does not have device address mappings, | client does not have device address mappings, | |||
and the metadata server sends a CB_NOTIFY_DEVICEID | and the metadata server sends a CB_NOTIFY_DEVICEID | |||
to add the device ID to the client's awareness | to add the device ID to the client's awareness | |||
and meanwhile the client sends GETDEVICEINFO on | and meanwhile the client sends GETDEVICEINFO on | |||
the device ID. This scenario is discussed in | the device ID. This scenario is discussed in | |||
<xref target="OP_GETDEVICEINFO_IMPLEMENTATION"/>. | <xref target="OP_GETDEVICEINFO_IMPLEMENTATION" format="default"/>. | |||
Another scenario is that the CB_NOTIFY_DEVICEID | Another scenario is that the CB_NOTIFY_DEVICEID | |||
is processed by the client before it processes | is processed by the client before it processes | |||
the results from LAYOUTGET. The client will send | the results from LAYOUTGET. The client will send | |||
a GETDEVICEINFO on the device ID. If the results | a GETDEVICEINFO on the device ID. If the results | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_LAYOUTRETURN" numbered="true" toc="default"> | |||
$ --> | <name>Operation 51: LAYOUTRETURN - Release Layout Information</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_LAYOUTRETURN_ARGUMENT" numbered="true" | |||
<!-- Copyright (C) The Internet Society (2006) --> | > | |||
<section anchor="OP_LAYOUTRETURN" title="Operation 51: LAYOUTRETURN - Release La | <name>ARGUMENT</name> | |||
yout Information" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_LAYOUTRETURN_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
/* 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 | |||
}; | }; | |||
struct layoutreturn_file4 { | struct layoutreturn_file4 { | |||
offset4 lrf_offset; | offset4 lrf_offset; | |||
length4 lrf_length; | length4 lrf_length; | |||
stateid4 lrf_stateid; | stateid4 lrf_stateid; | |||
/* layouttype4 specific data */ | /* layouttype4 specific data */ | |||
opaque lrf_body<>; | opaque lrf_body<>; | |||
}; | }; | |||
union layoutreturn4 switch(layoutreturn_type4 lr_returntype) { | union layoutreturn4 switch(layoutreturn_type4 lr_returntype) { | |||
case LAYOUTRETURN4_FILE: | case LAYOUTRETURN4_FILE: | |||
layoutreturn_file4 lr_layout; | layoutreturn_file4 lr_layout; | |||
default: | default: | |||
void; | void; | |||
}; | }; | |||
</artwork> | ||||
</figure> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LAYOUTRETURN_RESULT" numbered="true"> | |||
</figure> | <name>RESULT</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_LAYOUTRETURN_RESULT" title="RESULT"> | ||||
<figure> | ||||
<artwork> | ||||
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; | |||
default: | default: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_LAYOUTRETURN_DESCRIPTION" numbered="tr | |||
</figure> | ue"> | |||
</section> | <name>DESCRIPTION</name> | |||
<section toc="exclude" anchor="OP_LAYOUTRETURN_DESCRIPTION" title="DESCRIPTION | <t> | |||
"> | ||||
<t> | ||||
This operation returns from the client to the server | This operation returns from the client to the server | |||
one or more layouts represented by the client ID | one or more layouts represented by the client ID | |||
(derived from the session ID in the preceding SEQUENCE | (derived from the session ID in the preceding SEQUENCE | |||
operation), lora_layout_type, and lora_iomode. | operation), lora_layout_type, and lora_iomode. | |||
When lr_returntype is LAYOUTRETURN4_FILE, the | When lr_returntype is LAYOUTRETURN4_FILE, the | |||
returned layout is further identified by the current | returned layout is further identified by the current | |||
filehandle, lrf_offset, lrf_length, and lrf_stateid. | filehandle, lrf_offset, lrf_length, and lrf_stateid. | |||
If the lrf_length field is NFS4_UINT64_MAX, all bytes | If the lrf_length field is NFS4_UINT64_MAX, all bytes | |||
of the layout, starting at lrf_offset, are returned. | of the layout, starting at lrf_offset, are returned. | |||
When lr_returntype is LAYOUTRETURN4_FSID, the | When lr_returntype is LAYOUTRETURN4_FSID, the | |||
current filehandle is used to identify the file | current filehandle is used to identify the file | |||
system and all layouts matching the client ID, | system and all layouts matching the client ID, | |||
the fsid of the file system, lora_layout_type, and | the fsid of the file system, lora_layout_type, and | |||
lora_iomode are returned. When lr_returntype is | lora_iomode are returned. When lr_returntype is | |||
LAYOUTRETURN4_ALL, all layouts matching the client | LAYOUTRETURN4_ALL, all layouts matching the client | |||
ID, lora_layout_type, and lora_iomode are returned | ID, lora_layout_type, and lora_iomode are returned | |||
and the current filehandle is not used. After this | and the current filehandle is not used. After this | |||
call, the client MUST NOT use the returned layout(s) | call, the client <bcp14>MUST NOT</bcp14> use the returned layout(s) | |||
and the associated storage protocol to access the | and the associated storage protocol to access the | |||
file data. | file data. | |||
</t> | </t> | |||
<t> | <t> | |||
If the set of layouts designated in the case of | If the set of layouts designated in the case of | |||
LAYOUTRETURN4_FSID or LAYOUTRETURN4_ALL is empty, then no error | LAYOUTRETURN4_FSID or LAYOUTRETURN4_ALL is empty, then no error | |||
results. In the case of LAYOUTRETURN4_FILE, the byte-range | results. In the case of LAYOUTRETURN4_FILE, the byte-range | |||
specified is returned even if it is a subdivision of a layout | specified is returned even if it is a subdivision of a layout | |||
previously obtained with LAYOUTGET, a combination of multiple | previously obtained with LAYOUTGET, a combination of multiple | |||
layouts previously obtained with LAYOUTGET, or a combination | layouts previously obtained with LAYOUTGET, or a combination | |||
including some layouts previously obtained with LAYOUTGET, | including some layouts previously obtained with LAYOUTGET, | |||
and one or more subdivisions of such layouts. When the | and one or more subdivisions of such layouts. When the | |||
byte-range does not designate any bytes for which a layout | byte-range does not designate any bytes for which a layout | |||
is held for the specified file, client ID, layout type and | is held for the specified file, client ID, layout type and | |||
mode, no error results. | mode, no error results. | |||
See <xref target="bulk_layouts" /> for considerations with | See <xref target="bulk_layouts" format="default"/> for considerations wi th | |||
"bulk" return of layouts. | "bulk" return of layouts. | |||
</t> | </t> | |||
<t> | <t> | |||
The layout being returned may be a subset | The layout being returned may be a subset | |||
or superset of a layout specified by CB_LAYOUTRECALL. However, | or superset of a layout specified by CB_LAYOUTRECALL. However, | |||
if it is a subset, the recall is not complete until the full | if it is a subset, the recall is not complete until the full | |||
recalled scope has been returned. Recalled scope refers to the | recalled scope has been returned. Recalled scope refers to the | |||
byte-range in the case of LAYOUTRETURN4_FILE, the use of | byte-range in the case of LAYOUTRETURN4_FILE, the use of | |||
LAYOUTRETURN4_FSID, or the use of LAYOUTRETURN4_ALL. There must | LAYOUTRETURN4_FSID, or the use of LAYOUTRETURN4_ALL. There must | |||
be a LAYOUTRETURN with a matching scope to complete the return | be a LAYOUTRETURN with a matching scope to complete the return | |||
even if all current layout ranges have been previously individually | even if all current layout ranges have been previously individually | |||
returned. | returned. | |||
</t> | </t> | |||
<t> | <t> | |||
For all lr_returntype values, an iomode of LAYOUTIOMODE4_ANY | For all lr_returntype values, an iomode of LAYOUTIOMODE4_ANY | |||
specifies that all layouts that match the other arguments to | specifies that all layouts that match the other arguments to | |||
LAYOUTRETURN (i.e., client ID, lora_layout_type, and one of | LAYOUTRETURN (i.e., client ID, lora_layout_type, and one of | |||
current filehandle and range; fsid derived from current | current filehandle and range; fsid derived from current | |||
filehandle; or LAYOUTRETURN4_ALL) are being returned. | filehandle; or LAYOUTRETURN4_ALL) are being returned. | |||
</t> | </t> | |||
<t> | <t> | |||
In the case that lr_returntype is LAYOUTRETURN4_FILE, the | In the case that lr_returntype is LAYOUTRETURN4_FILE, the | |||
lrf_stateid provided by the client is a layout stateid as | lrf_stateid provided by the client is a layout stateid as | |||
returned from previous layout operations. Note that the "seqid" | returned from previous layout operations. Note that the "seqid" | |||
field of lrf_stateid MUST NOT be zero. See Sections | field of lrf_stateid <bcp14>MUST NOT</bcp14> be zero. See Sections | |||
<xref target="stateid" format="counter" />, <xref | <xref target="stateid" format="counter"/>, <xref target="layout_stateid" f | |||
target="layout_stateid" format="counter" />, and | ormat="counter"/>, and | |||
<xref target="pnfs_operation_sequencing" format="counter" /> for a further | <xref target="pnfs_operation_sequencing" format="counter"/> for a further | |||
discussion and requirements. | discussion and requirements. | |||
</t> | </t> | |||
<t> | <t> | |||
Return of a layout or all layouts does not invalidate the | Return of a layout or all layouts does not invalidate the | |||
mapping of storage device ID to a storage device address. The | mapping of storage device ID to a storage device address. The | |||
mapping remains in effect until specifically changed or deleted via | mapping remains in effect until specifically changed or deleted via | |||
device ID notification callbacks. | device ID notification callbacks. | |||
Of course if there are no remaining | Of course if there are no remaining | |||
layouts that refer to a previously used device ID, the server is | layouts that refer to a previously used device ID, the server is | |||
free to delete a device ID without a notification callback, which | free to delete a device ID without a notification callback, which | |||
will be the case when notifications are not in effect. | will be the case when notifications are not in effect. | |||
</t> | </t> | |||
<t> | <t> | |||
If the lora_reclaim field is set to TRUE, the | If the lora_reclaim field is set to TRUE, the | |||
client is attempting to return a layout that | client is attempting to return a layout that | |||
was acquired before the restart of the metadata | was acquired before the restart of the metadata | |||
server during the metadata server's grace period. | server during the metadata server's grace period. | |||
When returning layouts that were acquired during | When returning layouts that were acquired during | |||
the metadata server's grace period, the client MUST set the | the metadata server's grace period, the client <bcp14>MUST</bcp14> set the | |||
lora_reclaim field to FALSE. The lora_reclaim field | lora_reclaim field to FALSE. The lora_reclaim field | |||
MUST be set to FALSE also when lr_layoutreturn is | <bcp14>MUST</bcp14> be set to FALSE also when lr_layoutreturn is | |||
LAYOUTRETURN4_FSID or LAYOUTRETURN4_ALL. See <xref | LAYOUTRETURN4_FSID or LAYOUTRETURN4_ALL. See <xref target="OP_LAYOUTCOMMIT | |||
target="OP_LAYOUTCOMMIT">LAYOUTCOMMIT </xref> for | " format="default">LAYOUTCOMMIT </xref> for | |||
more details. | more details. | |||
</t> | </t> | |||
<t> | <t> | |||
Layouts may be returned when recalled or voluntarily (i.e., | Layouts may be returned when recalled or voluntarily (i.e., | |||
before the server has recalled them). In either case, the client | before the server has recalled them). In either case, the client | |||
must properly propagate state changed under the context of the | must properly propagate state changed under the context of the | |||
layout to the storage device(s) or to the metadata server before | layout to the storage device(s) or to the metadata server before | |||
returning the layout. | returning the layout. | |||
</t> | </t> | |||
<t> | <t> | |||
If the client returns the layout in response to a | If the client returns the layout in response to a | |||
CB_LAYOUTRECALL where the lor_recalltype field of the | CB_LAYOUTRECALL where the lor_recalltype field of the | |||
clora_recall field was LAYOUTRECALL4_FILE, the client | clora_recall field was LAYOUTRECALL4_FILE, the client | |||
should use the lor_stateid value from CB_LAYOUTRECALL | should use the lor_stateid value from CB_LAYOUTRECALL | |||
as the value for lrf_stateid. Otherwise, it should | as the value for lrf_stateid. Otherwise, it should | |||
use logr_stateid (from a previous LAYOUTGET result) | use logr_stateid (from a previous LAYOUTGET result) | |||
or lorr_stateid (from a previous LAYRETURN result). | or lorr_stateid (from a previous LAYRETURN result). | |||
This is done to indicate the point in time (in terms | This is done to indicate the point in time (in terms | |||
of layout stateid transitions) when the recall was | of layout stateid transitions) when the recall was | |||
sent. The client uses the precise lora_recallstateid | sent. The client uses the precise lora_recallstateid | |||
value and MUST NOT set the stateid's seqid to | value and <bcp14>MUST NOT</bcp14> set the stateid's seqid to | |||
zero; otherwise, NFS4ERR_BAD_STATEID MUST be | zero; otherwise, NFS4ERR_BAD_STATEID <bcp14>MUST</bcp14> be | |||
returned. NFS4ERR_OLD_STATEID can be returned if | returned. NFS4ERR_OLD_STATEID can be returned if | |||
the client is using an old seqid, and the server | the client is using an old seqid, and the server | |||
knows the client should not be using the old | knows the client should not be using the old | |||
seqid. For example, the client uses the seqid on slot 1 of | seqid. For example, the client uses the seqid on slot 1 of | |||
the session, receives the response with the new | the session, receives the response with the new | |||
seqid, and uses the slot to send another request | seqid, and uses the slot to send another request | |||
with the old seqid. | with the old seqid. | |||
</t> | </t> | |||
<t> | <t> | |||
If a client fails to return a layout | If a client fails to return a layout | |||
in a timely manner, then the metadata server SHOULD use its | in a timely manner, then the metadata server <bcp14>SHOULD</bcp14> use its | |||
control protocol with the storage devices to fence the client | control protocol with the storage devices to fence the client | |||
from accessing the data referenced by the layout. See | from accessing the data referenced by the layout. See | |||
<xref target="recalling_layout" /> for more details. | <xref target="recalling_layout" format="default"/> for more details. | |||
</t> | </t> | |||
<t> | <t> | |||
If the LAYOUTRETURN request sets the lora_reclaim field to TRUE after | If the LAYOUTRETURN request sets the lora_reclaim field to TRUE after | |||
the metadata server's grace period, NFS4ERR_NO_GRACE is returned. | the metadata server's grace period, NFS4ERR_NO_GRACE is returned. | |||
</t> | </t> | |||
<t> | <t> | |||
If the LAYOUTRETURN request sets the lora_reclaim field to TRUE | If the LAYOUTRETURN request sets the lora_reclaim field to TRUE | |||
and lr_returntype is set to LAYOUTRETURN4_FSID or LAYOUTRETURN4_ALL, | and lr_returntype is set to LAYOUTRETURN4_FSID or LAYOUTRETURN4_ALL, | |||
NFS4ERR_INVAL is returned. | NFS4ERR_INVAL is returned. | |||
</t> | </t> | |||
<t> | <t> | |||
If the client sets the lr_returntype field to | If the client sets the lr_returntype field to | |||
LAYOUTRETURN4_FILE, then the lrs_stateid field | LAYOUTRETURN4_FILE, then the lrs_stateid field | |||
will represent the layout stateid as updated for | will represent the layout stateid as updated for | |||
this operation's processing; the current stateid | this operation's processing; the current stateid | |||
will also be updated to match the returned value. | will also be updated to match the returned value. | |||
If the last byte of any layout for the current | If the last byte of any layout for the current | |||
file, client ID, and layout type is being returned | file, client ID, and layout type is being returned | |||
and there are no remaining pending CB_LAYOUTRECALL | and there are no remaining pending CB_LAYOUTRECALL | |||
operations for which a LAYOUTRETURN operation must be | operations for which a LAYOUTRETURN operation must be | |||
done, lrs_present MUST be FALSE, and no stateid | done, lrs_present <bcp14>MUST</bcp14> be FALSE, and no stateid | |||
will be returned. In addition, the COMPOUND request's current | will be returned. In addition, the COMPOUND request's current | |||
stateid will be set to the all-zeroes special stateid | stateid will be set to the all-zeroes special stateid | |||
(see <xref target="current_stateid"/>). The server | (see <xref target="current_stateid" format="default"/>). The server | |||
MUST reject with NFS4ERR_BAD_STATEID any further | <bcp14>MUST</bcp14> reject with NFS4ERR_BAD_STATEID any further | |||
use of the current stateid in that COMPOUND until | use of the current stateid in that COMPOUND until | |||
the current stateid is re-established by a later | the current stateid is re-established by a later | |||
stateid-returning operation. | stateid-returning operation. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle retains its value. | On success, the current filehandle retains its value. | |||
</t> | </t> | |||
<t> | <t> | |||
If the EXCHGID4_FLAG_BIND_PRINC_STATEID | If the EXCHGID4_FLAG_BIND_PRINC_STATEID | |||
capability is set on the client ID (see <xref | capability is set on the client ID (see <xref target="OP_EXCHANGE_ID" forma | |||
target="OP_EXCHANGE_ID"/>), the server will | t="default"/>), the server will | |||
require that the principal, security flavor, | require that the principal, security flavor, | |||
and if applicable, the GSS mechanism, combination | and if applicable, the GSS mechanism, combination | |||
that acquired the layout also be the one to send | that acquired the layout also be the one to send | |||
LAYOUTRETURN. This might not be possible | LAYOUTRETURN. This might not be possible | |||
if credentials for the principal are no | if credentials for the principal are no | |||
longer available. The server will allow the | longer available. The server will allow the | |||
machine credential or SSV credential (see <xref | machine credential or SSV credential (see <xref target="OP_EXCHANGE_ID" for | |||
target="OP_EXCHANGE_ID" />) to send LAYOUTRETURN | mat="default"/>) to send LAYOUTRETURN | |||
if LAYOUTRETURN's operation code was set in the | if LAYOUTRETURN's operation code was set in the | |||
spo_must_allow result of EXCHANGE_ID. | spo_must_allow result of EXCHANGE_ID. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_LAYOUTRETURN_IMPLEMENTATION" title="IMPLEMEN | <section toc="exclude" anchor="OP_LAYOUTRETURN_IMPLEMENTATION" numbered= | |||
TATION"> | "true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
The final LAYOUTRETURN operation in response to a CB_LAYOUTRECALL | The final LAYOUTRETURN operation in response to a CB_LAYOUTRECALL | |||
callback MUST be serialized with any outstanding, intersecting | callback <bcp14>MUST</bcp14> be serialized with any outstanding, intersectin g | |||
LAYOUTRETURN operations. Note that it is possible that while a | LAYOUTRETURN operations. Note that it is possible that while a | |||
client is returning the layout for some recalled range, the server | client is returning the layout for some recalled range, the server | |||
may recall a superset of that range (e.g., LAYOUTRECALL4_ALL); the final | may recall a superset of that range (e.g., LAYOUTRECALL4_ALL); the final | |||
return operation for the latter must block until the former layout | return operation for the latter must block until the former layout | |||
recall is done. | recall is done. | |||
</t> | </t> | |||
<t> | <t> | |||
Returning all layouts in a file system using LAYOUTRETURN4_FSID is | Returning all layouts in a file system using LAYOUTRETURN4_FSID is | |||
typically done in response to a CB_LAYOUTRECALL for that file system | typically done in response to a CB_LAYOUTRECALL for that file system | |||
as the final return operation. Similarly, LAYOUTRETURN4_ALL | as the final return operation. Similarly, LAYOUTRETURN4_ALL | |||
is used in response to a recall callback for all layouts. It is | is used in response to a recall callback for all layouts. It is | |||
possible that the client already returned some outstanding layouts | possible that the client already returned some outstanding layouts | |||
via individual LAYOUTRETURN calls and the call for | via individual LAYOUTRETURN calls and the call for | |||
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" /> | 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 MAY delete the device ID. | device ID, the server <bcp14>MAY</bcp14> delete the device ID. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_SECINFO_NO_NAME" numbered="true" toc="default"> | |||
$ --> | <name>Operation 52: SECINFO_NO_NAME - Get Security on Unnamed Object</na | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | me> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <section toc="exclude" anchor="OP_SECINFO_NO_NAME_ARGUMENT" numbered="tr | |||
<section title="Operation 52: SECINFO_NO_NAME - Get Security on Unnamed Object" | ue"> | |||
anchor="OP_SECINFO_NO_NAME"> | <name>ARGUMENT</name> | |||
<sourcecode type="xdr"><![CDATA[ | ||||
<section toc="exclude" anchor="OP_SECINFO_NO_NAME_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
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> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_SECINFO_NO_NAME_RESULT" numbered="true | |||
</section> | "> | |||
<section toc="exclude" anchor="OP_SECINFO_NO_NAME_RESULT" title="RESULT"> | <name>RESULT</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
/* 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> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_SECINFO_NO_NAME_DESCRIPTION" numbered= | |||
</section> | "true"> | |||
<section toc="exclude" anchor="OP_SECINFO_NO_NAME_DESCRIPTION" title="DESCRIPT | <name>DESCRIPTION</name> | |||
ION"> | <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 | |||
works with objects that are accessed by filehandle. | works with objects that are accessed by filehandle. | |||
</t> | </t> | |||
<t> | <t> | |||
There are two styles of SECINFO_NO_NAME, as determined by the | There are two styles of SECINFO_NO_NAME, as determined by the | |||
value of the secinfo_style4 enumeration. If SECINFO_STYLE4_CURRENT_FH is | value of the secinfo_style4 enumeration. If SECINFO_STYLE4_CURRENT_FH is | |||
passed, then SECINFO_NO_NAME is querying for the required | passed, then SECINFO_NO_NAME is querying for the required | |||
security for the current filehandle. If SECINFO_STYLE4_PARENT is passed, t hen | security for the current filehandle. If SECINFO_STYLE4_PARENT is passed, t hen | |||
SECINFO_NO_NAME is querying for the required security of the | SECINFO_NO_NAME is querying for the required security of the | |||
current filehandle's parent. If the style selected is SECINFO_STYLE4_PAREN T, | current filehandle's parent. If the style selected is SECINFO_STYLE4_PAREN T, | |||
then SECINFO should apply the same access methodology used for | then SECINFO should apply the same access methodology used for | |||
LOOKUPP when evaluating the traversal to the parent directory. | LOOKUPP when evaluating the traversal to the parent directory. | |||
Therefore, if the requester does not have the appropriate access | Therefore, if the requester does not have the appropriate access | |||
to LOOKUPP the parent, then SECINFO_NO_NAME must behave the same | to LOOKUPP the parent, then SECINFO_NO_NAME must behave the same | |||
way and return NFS4ERR_ACCESS. | way and return NFS4ERR_ACCESS. | |||
</t> | </t> | |||
<t> | <t> | |||
If PUTFH, PUTPUBFH, PUTROOTFH, or RESTOREFH returns | If PUTFH, PUTPUBFH, PUTROOTFH, or RESTOREFH returns | |||
NFS4ERR_WRONGSEC, then the client resolves the | NFS4ERR_WRONGSEC, then the client resolves the | |||
situation by sending a COMPOUND request that consists of | situation by sending a COMPOUND request that consists of | |||
PUTFH, PUTPUBFH, or PUTROOTFH immediately followed by | PUTFH, PUTPUBFH, or PUTROOTFH immediately followed by | |||
SECINFO_NO_NAME, style SECINFO_STYLE4_CURRENT_FH. | SECINFO_NO_NAME, style SECINFO_STYLE4_CURRENT_FH. | |||
See <xref target="Security_Service_Negotiation" /> | See <xref target="Security_Service_Negotiation" format="default"/> | |||
for instructions on dealing with NFS4ERR_WRONGSEC error | for instructions on dealing with NFS4ERR_WRONGSEC error | |||
returns from PUTFH, PUTROOTFH, PUTPUBFH, or RESTOREFH. | returns from PUTFH, PUTROOTFH, PUTPUBFH, or RESTOREFH. | |||
</t> | </t> | |||
<t> | <t> | |||
If SECINFO_STYLE4_PARENT is specified and there is no parent | If SECINFO_STYLE4_PARENT is specified and there is no parent | |||
directory, SECINFO_NO_NAME MUST return NFS4ERR_NOENT. | directory, SECINFO_NO_NAME <bcp14>MUST</bcp14> return NFS4ERR_NOENT. | |||
</t> | </t> | |||
<t> | <t> | |||
On success, the current filehandle is consumed | On success, the current filehandle is consumed | |||
(see <xref target="aftersecinfo" />), and if the | (see <xref target="aftersecinfo" format="default"/>), and if the | |||
next operation after SECINFO_NO_NAME tries to use | next operation after SECINFO_NO_NAME tries to use | |||
the current filehandle, that operation will fail | the current filehandle, that operation will fail | |||
with the status NFS4ERR_NOFILEHANDLE. | with the status NFS4ERR_NOFILEHANDLE. | |||
</t> | </t> | |||
<t> | <t> | |||
Everything else about SECINFO_NO_NAME is the same as SECINFO. | Everything else about SECINFO_NO_NAME is the same as SECINFO. | |||
See the discussion on SECINFO (<xref target="OP_SECINFO_DESCRIPTION"/>). | See the discussion on SECINFO (<xref target="OP_SECINFO_DESCRIPTION" forma | |||
</t> | t="default"/>). | |||
</section> | </t> | |||
<section toc="exclude" anchor="OP_SECINFO_NO_NAME_IMPLEMENTATION" title="IMPLE | </section> | |||
MENTATION"> | <section toc="exclude" anchor="OP_SECINFO_NO_NAME_IMPLEMENTATION" number | |||
<t> | ed="true"> | |||
See the discussion on SECINFO (<xref target="OP_SECINFO_IMPLEMENTATION" /> | <name>IMPLEMENTATION</name> | |||
). | <t> | |||
</t> | See the discussion on SECINFO (<xref target="OP_SECINFO_IMPLEMENTATION" fo | |||
</section> | rmat="default"/>). | |||
</section> | </t> | |||
</section> | ||||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | </section> | |||
$ --> | <section anchor="OP_SEQUENCE" numbered="true" toc="default"> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <name>Operation 53: SEQUENCE - Supply Per-Procedure Sequencing and Contr | |||
<!-- Copyright (C) The Internet Society (2006) --> | ol</name> | |||
<section anchor="OP_SEQUENCE" title="Operation 53: SEQUENCE - Supply Per-Procedu | <section toc="exclude" anchor="OP_SEQUENCE_ARGUMENT" numbered="true"> | |||
re Sequencing and Control" > | <name>ARGUMENT</name> | |||
<sourcecode type="xdr"><![CDATA[ | ||||
<section toc="exclude" anchor="OP_SEQUENCE_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_SEQUENCE_RESULT" numbered="true"> | |||
</figure> | <name>RESULT</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_SEQUENCE_RESULT" title="RESULT"> | ||||
<figure> | ||||
<artwork> | ||||
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 39086 ¶ | skipping to change at line 39042 ¶ | |||
slotid4 sr_highest_slotid; | slotid4 sr_highest_slotid; | |||
slotid4 sr_target_highest_slotid; | slotid4 sr_target_highest_slotid; | |||
uint32_t sr_status_flags; | uint32_t sr_status_flags; | |||
}; | }; | |||
union SEQUENCE4res switch (nfsstat4 sr_status) { | union SEQUENCE4res switch (nfsstat4 sr_status) { | |||
case NFS4_OK: | case NFS4_OK: | |||
SEQUENCE4resok sr_resok4; | SEQUENCE4resok sr_resok4; | |||
default: | default: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_SEQUENCE_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_SEQUENCE_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
The SEQUENCE operation is | The SEQUENCE operation is | |||
used by the server to implement session request control | used by the server to implement session request control | |||
and the reply cache semantics. | and the reply cache semantics. | |||
</t> | </t> | |||
<t> | <t> | |||
SEQUENCE MUST appear as the first operation of any COMPOUND | SEQUENCE <bcp14>MUST</bcp14> appear as the first operation of any COMPOUND | |||
in which it appears. The error NFS4ERR_SEQUENCE_POS will be | in which it appears. The error NFS4ERR_SEQUENCE_POS will be | |||
returned when it is found in any position in a COMPOUND | returned when it is found in any position in a COMPOUND | |||
beyond the first. Operations other than SEQUENCE, BIND_CONN_TO_SESSION, | beyond the first. Operations other than SEQUENCE, BIND_CONN_TO_SESSION, | |||
EXCHANGE_ID, CREATE_SESSION, and DESTROY_SESSION, | EXCHANGE_ID, CREATE_SESSION, and DESTROY_SESSION, | |||
MUST NOT appear as the first operation in a | <bcp14>MUST NOT</bcp14> appear as the first operation in a | |||
COMPOUND. Such operations MUST yield the error NFS4ERR_OP_NOT_IN_SESSION | COMPOUND. Such operations <bcp14>MUST</bcp14> yield the error NFS4ERR_OP_ | |||
NOT_IN_SESSION | ||||
if they do appear at the start of a COMPOUND. | if they do appear at the start of a COMPOUND. | |||
</t> | </t> | |||
<t> | <t> | |||
If SEQUENCE is received on a connection not associated with the | If SEQUENCE is received on a connection not associated with the | |||
session via CREATE_SESSION or BIND_CONN_TO_SESSION, and | session via CREATE_SESSION or BIND_CONN_TO_SESSION, and | |||
connection association enforcement is enabled | connection association enforcement is enabled | |||
(see <xref target="OP_EXCHANGE_ID" />), then | (see <xref target="OP_EXCHANGE_ID" format="default"/>), then | |||
the server returns NFS4ERR_CONN_NOT_BOUND_TO_SESSION. | the server returns NFS4ERR_CONN_NOT_BOUND_TO_SESSION. | |||
</t> | </t> | |||
<t> | <t> | |||
The sa_sessionid argument identifies the session to which this | The sa_sessionid argument identifies the session to which this | |||
request applies. The sr_sessionid result MUST equal | request applies. The sr_sessionid result <bcp14>MUST</bcp14> equal | |||
sa_sessionid. | sa_sessionid. | |||
</t> | </t> | |||
<t> | <t> | |||
The sa_slotid argument is the index in the reply cache | The sa_slotid argument is the index in the reply cache | |||
for the request. The sa_sequenceid field is the sequence | for the request. The sa_sequenceid field is the sequence | |||
number of the request for the reply cache entry (slot). | number of the request for the reply cache entry (slot). | |||
The sr_slotid result MUST equal sa_slotid. The sr_sequenceid | The sr_slotid result <bcp14>MUST</bcp14> equal sa_slotid. The sr_sequenceid | |||
result MUST equal sa_sequenceid. | result <bcp14>MUST</bcp14> equal sa_sequenceid. | |||
</t> | </t> | |||
<t> | <t> | |||
The sa_highest_slotid argument is the highest slot ID | The sa_highest_slotid argument is the highest slot ID | |||
for which the client has a request outstanding; it could be | for which the client has a request outstanding; it could be | |||
equal to sa_slotid. | equal to sa_slotid. | |||
The server returns two "highest_slotid" values: sr_highest_slotid | The server returns two "highest_slotid" values: sr_highest_slotid | |||
and sr_target_highest_slotid. The former is the highest slot ID | and sr_target_highest_slotid. The former is the highest slot ID | |||
the server will accept in future SEQUENCE operation, and | the server will accept in future SEQUENCE operation, and | |||
SHOULD NOT be less than the value of sa_highest_slotid | <bcp14>SHOULD NOT</bcp14> be less than the value of sa_highest_slotid | |||
(but see | (but see | |||
<xref target="Slot_Identifiers_and_Server_Reply_Cache" /> | <xref target="Slot_Identifiers_and_Server_Reply_Cache" format="default"/> | |||
for an exception). | for an exception). | |||
The latter is the highest slot ID the server would prefer the | The latter is the highest slot ID the server would prefer the | |||
client use on a future SEQUENCE operation. | client use on a future SEQUENCE operation. | |||
</t> | </t> | |||
<t> | <t> | |||
If sa_cachethis is TRUE, then the client is requesting that | If sa_cachethis is TRUE, then the client is requesting that | |||
the server cache the entire | the server cache the entire | |||
reply in the server's reply cache; therefore, the server MUST | reply in the server's reply cache; therefore, the server <bcp14>MUST</bcp14 | |||
cache the reply (see <xref target="optional_reply_caching" />). | > | |||
The server MAY cache the reply if sa_cachethis is FALSE. | cache the reply (see <xref target="optional_reply_caching" format="default" | |||
/>). | ||||
The server <bcp14>MAY</bcp14> cache the reply if sa_cachethis is FALSE. | ||||
If the server does not cache the entire reply, it | If the server does not cache the entire reply, it | |||
MUST still record that it executed the request at | <bcp14>MUST</bcp14> still record that it executed the request at | |||
the specified slot and sequence ID. | the specified slot and sequence ID. | |||
</t> | </t> | |||
<t> | <t> | |||
The response to the SEQUENCE operation contains a | The response to the SEQUENCE operation contains a | |||
word of status flags (sr_status_flags) that can | word of status flags (sr_status_flags) that can | |||
provide to the client information related to the | provide to the client information related to the | |||
status of the client's lock state and communications | status of the client's lock state and communications | |||
paths. Note that any status bits relating to lock | paths. Note that any status bits relating to lock | |||
state MAY be reset when lock state is lost due to a | state <bcp14>MAY</bcp14> be reset when lock state is lost due to a | |||
server restart (even if the session is persistent across | server restart (even if the session is persistent across | |||
restarts; session persistence does not imply | restarts; session persistence does not imply | |||
lock state persistence) | lock state persistence) | |||
or the establishment of a new client | or the establishment of a new client | |||
instance. | instance. | |||
<list style='hanging'> | </t> | |||
<t hangText="SEQ4_STATUS_CB_PATH_DOWN"><vspace /> | <dl newline="true" spacing="normal"> | |||
<dt>SEQ4_STATUS_CB_PATH_DOWN</dt> | ||||
<dd> | ||||
When set, indicates that the client has no | When set, indicates that the client has no | |||
operational backchannel path for any session | operational backchannel path for any session | |||
associated with the client ID, making it | associated with the client ID, making it | |||
necessary for the client to re-establish one. | necessary for the client to re-establish one. | |||
This bit | This bit | |||
remains set on all SEQUENCE responses on all sessions | remains set on all SEQUENCE responses on all sessions | |||
associated with the client ID | associated with the client ID | |||
until at least one backchannel is | until at least one backchannel is | |||
available on any session associated with the client ID. | available on any session associated with the client ID. | |||
If the client fails to re-establish a | If the client fails to re-establish a | |||
backchannel for the client ID, it is subject to | backchannel for the client ID, it is subject to | |||
having recallable state revoked. | having recallable state revoked. | |||
</t> | </dd> | |||
<t hangText="SEQ4_STATUS_CB_PATH_DOWN_SESSION"><vspace /> | <dt>SEQ4_STATUS_CB_PATH_DOWN_SESSION</dt> | |||
<dd> | ||||
When set, indicates that the session has | When set, indicates that the session has | |||
no operational backchannel. There are two reasons | no operational backchannel. There are two reasons | |||
why SEQ4_STATUS_CB_PATH_DOWN_SESSION may be set and not | why SEQ4_STATUS_CB_PATH_DOWN_SESSION may be set and not | |||
SEQ4_STATUS_CB_PATH_DOWN. First is that a callback operation | SEQ4_STATUS_CB_PATH_DOWN. First is that a callback operation | |||
that applies specifically to the | that applies specifically to the | |||
session (e.g., CB_RECALL_SLOT, see <xref | session (e.g., CB_RECALL_SLOT, see <xref target="OP_CB_RECALL_SLOT" fo | |||
target="OP_CB_RECALL_SLOT" />) needs to be sent. | rmat="default"/>) needs to be sent. | |||
Second is that the server did send a callback operation, | Second is that the server did send a callback operation, | |||
but the connection was lost before the reply. The | but the connection was lost before the reply. The | |||
server cannot be sure whether or not the client received the | server cannot be sure whether or not the client received the | |||
callback operation, and so, per rules on | callback operation, and so, per rules on | |||
request retry, the server MUST retry the callback | request retry, the server <bcp14>MUST</bcp14> retry the callback | |||
operation over the same session. The | operation over the same session. The | |||
SEQ4_STATUS_CB_PATH_DOWN_SESSION bit is the indication | SEQ4_STATUS_CB_PATH_DOWN_SESSION bit is the indication | |||
to the client that it needs to associate a connection | to the client that it needs to associate a connection | |||
to the session's backchannel. | to the session's backchannel. | |||
This bit remains set on all SEQUENCE responses of the | This bit remains set on all SEQUENCE responses of the | |||
session until a connection is associated with the | session until a connection is associated with the | |||
session's a backchannel. | session's a backchannel. | |||
If the client fails to re-establish a | If the client fails to re-establish a | |||
backchannel for the session, it is subject to | backchannel for the session, it is subject to | |||
having recallable state revoked. | having recallable state revoked. | |||
</t> | </dd> | |||
<t hangText="SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRING"><vspace /> | <dt>SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRING</dt> | |||
<dd> | ||||
<t> | ||||
When set, indicates that all GSS contexts or RPCSEC_GSS handles | When set, indicates that all GSS contexts or RPCSEC_GSS handles | |||
assigned to the session's backchannel will expire within a | assigned to the session's backchannel will expire within a | |||
period equal to the lease time. This bit remains set on all | period equal to the lease time. This bit remains set on all | |||
SEQUENCE replies until at least one of the following are true: | SEQUENCE replies until at least one of the following are true: | |||
<list style='symbols'> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <li> | |||
All SSV RPCSEC_GSS handles on the session's backchannel | All SSV RPCSEC_GSS handles on the session's backchannel | |||
have been destroyed and all non-SSV GSS contexts have expired. | have been destroyed and all non-SSV GSS contexts have expired. | |||
</t> | </li> | |||
<t> | <li> | |||
At least one more SSV RPCSEC_GSS handle has been added to | At least one more SSV RPCSEC_GSS handle has been added to | |||
the backchannel. | the backchannel. | |||
</t> | </li> | |||
<t> | <li> | |||
The expiration time of at least one non-SSV GSS context | The expiration time of at least one non-SSV GSS context | |||
of an RPCSEC_GSS handle | of an RPCSEC_GSS handle | |||
is beyond the lease period from the current | is beyond the lease period from the current | |||
time (relative to the time of when a SEQUENCE | time (relative to the time of when a SEQUENCE | |||
response was sent) | response was sent) | |||
</t> | </li> | |||
</ul> | ||||
</list> | </dd> | |||
</t> | <dt>SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRED</dt> | |||
<t hangText="SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRED"><vspace /> | <dd> | |||
When set, indicates all non-SSV GSS contexts and all | When set, indicates all non-SSV GSS contexts and all | |||
SSV RPCSEC_GSS handles assigned | SSV RPCSEC_GSS handles assigned | |||
to the session's backchannel have expired or have been | to the session's backchannel have expired or have been | |||
destroyed. | destroyed. | |||
This bit remains set on all SEQUENCE replies | This bit remains set on all SEQUENCE replies | |||
until at least one non-expired non-SSV GSS context for the | until at least one non-expired non-SSV GSS context for the | |||
session's backchannel has been established or at least one | session's backchannel has been established or at least one | |||
SSV RPCSEC_GSS handle has been assigned to the backchannel. | SSV RPCSEC_GSS handle has been assigned to the backchannel. | |||
</t> | </dd> | |||
<t hangText="SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED"><vspace /> | <dt>SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED</dt> | |||
<dd> | ||||
When set, indicates that the lease has expired | When set, indicates that the lease has expired | |||
and as a result the server released all of the | and as a result the server released all of the | |||
client's locking state. This status bit remains | client's locking state. This status bit remains | |||
set on all SEQUENCE replies until the loss of | set on all SEQUENCE replies until the loss of | |||
all such locks has been acknowledged by use of | all such locks has been acknowledged by use of | |||
FREE_STATEID (see <xref target="OP_FREE_STATEID" | FREE_STATEID (see <xref target="OP_FREE_STATEID" format="default"/>), | |||
/>), or by establishing a new client instance by | or by establishing a new client instance by | |||
destroying all sessions (via DESTROY_SESSION), | destroying all sessions (via DESTROY_SESSION), | |||
the client ID (via DESTROY_CLIENTID), and then | the client ID (via DESTROY_CLIENTID), and then | |||
invoking EXCHANGE_ID and CREATE_SESSION to | invoking EXCHANGE_ID and CREATE_SESSION to | |||
establish a new client ID. | establish a new client ID. | |||
</t> | </dd> | |||
<t hangText="SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED"><vspace /> | <dt>SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED</dt> | |||
<dd> | ||||
When set, indicates that some subset of the client's locks | When set, indicates that some subset of the client's locks | |||
have been revoked due to expiration of the lease period | have been revoked due to expiration of the lease period | |||
followed by another client's conflicting LOCK operation. | followed by another client's conflicting LOCK operation. | |||
This status bit remains set on all SEQUENCE replies | This status bit remains set on all SEQUENCE replies | |||
until the loss of all | until the loss of all | |||
such locks has been acknowledged by use of FREE_STATEID. | such locks has been acknowledged by use of FREE_STATEID. | |||
</t> | </dd> | |||
<t hangText="SEQ4_STATUS_ADMIN_STATE_REVOKED"><vspace /> | <dt>SEQ4_STATUS_ADMIN_STATE_REVOKED</dt> | |||
<dd> | ||||
When set, indicates that one or more locks have been revoked | When set, indicates that one or more locks have been revoked | |||
without expiration of the lease period, due to administrative | without expiration of the lease period, due to administrative | |||
action. This status bit remains set on all SEQUENCE replies | action. This status bit remains set on all SEQUENCE replies | |||
until the loss of all | until the loss of all | |||
such locks has been acknowledged by use of FREE_STATEID. | such locks has been acknowledged by use of FREE_STATEID. | |||
</t> | </dd> | |||
<t hangText="SEQ4_STATUS_RECALLABLE_STATE_REVOKED"><vspace /> | <dt>SEQ4_STATUS_RECALLABLE_STATE_REVOKED</dt> | |||
<dd> | ||||
When set, indicates that one or more recallable | When set, indicates that one or more recallable | |||
objects have been revoked without expiration | objects have been revoked without expiration | |||
of the lease period, due to the client's | of the lease period, due to the client's | |||
failure to return them when recalled, which | failure to return them when recalled, which | |||
may be a consequence of there being no working | may be a consequence of there being no working | |||
backchannel and the client failing to re-establish | backchannel and the client failing to re-establish | |||
a backchannel per the SEQ4_STATUS_CB_PATH_DOWN, | a backchannel per the SEQ4_STATUS_CB_PATH_DOWN, | |||
SEQ4_STATUS_CB_PATH_DOWN_SESSION, or | SEQ4_STATUS_CB_PATH_DOWN_SESSION, or | |||
SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRED status flags. | SEQ4_STATUS_CB_GSS_CONTEXTS_EXPIRED status flags. | |||
This status bit remains set on all SEQUENCE | This status bit remains set on all SEQUENCE | |||
replies until the loss of all such locks has | replies until the loss of all such locks has | |||
been acknowledged by use of FREE_STATEID. | been acknowledged by use of FREE_STATEID. | |||
</t> | </dd> | |||
<t hangText="SEQ4_STATUS_LEASE_MOVED"><vspace /> | <dt>SEQ4_STATUS_LEASE_MOVED</dt> | |||
<dd> | ||||
When set, indicates that responsibility for lease renewal has | When set, indicates that responsibility for lease renewal has | |||
been transferred to one or more new servers. This condition | been transferred to one or more new servers. This condition | |||
will continue until the client receives an NFS4ERR_MOVED | will continue until the client receives an NFS4ERR_MOVED | |||
error and the server receives the subsequent GETATTR for the | error and the server receives the subsequent GETATTR for the | |||
fs_locations or fs_locations_info attribute for an access to | fs_locations or fs_locations_info attribute for an access to | |||
each file system for which a lease has been moved to a new | each file system for which a lease has been moved to a new | |||
server. See <xref target="transferred_lease" />. | server. See <xref target="transferred_lease" format="default"/>. | |||
</t> | </dd> | |||
<t hangText="SEQ4_STATUS_RESTART_RECLAIM_NEEDED"><vspace /> | <dt>SEQ4_STATUS_RESTART_RECLAIM_NEEDED</dt> | |||
<dd> | ||||
When set, indicates that due to server | When set, indicates that due to server | |||
restart, the client must reclaim locking state. | restart, the client must reclaim locking state. | |||
Until the client sends a global RECLAIM_COMPLETE | Until the client sends a global RECLAIM_COMPLETE | |||
(<xref target="OP_RECLAIM_COMPLETE" />), every | (<xref target="OP_RECLAIM_COMPLETE" format="default"/>), every | |||
SEQUENCE operation will return | SEQUENCE operation will return | |||
SEQ4_STATUS_RESTART_RECLAIM_NEEDED. | SEQ4_STATUS_RESTART_RECLAIM_NEEDED. | |||
</t> | </dd> | |||
<t hangText="SEQ4_STATUS_BACKCHANNEL_FAULT"><vspace /> | <dt>SEQ4_STATUS_BACKCHANNEL_FAULT</dt> | |||
<dd> | ||||
The server has encountered an unrecoverable fault | The server has encountered an unrecoverable fault | |||
with the backchannel (e.g., it has lost track of the | with the backchannel (e.g., it has lost track of the | |||
sequence ID for a slot in the backchannel). The | sequence ID for a slot in the backchannel). The | |||
client MUST stop sending more requests on the | client <bcp14>MUST</bcp14> stop sending more requests on the | |||
session's fore channel, wait for all outstanding requests to | session's fore channel, wait for all outstanding requests to | |||
complete on the fore and back channel, and then | complete on the fore and back channel, and then | |||
destroy the session. | destroy the session. | |||
</t> | </dd> | |||
<t hangText="SEQ4_STATUS_DEVID_CHANGED"><vspace /> | <dt>SEQ4_STATUS_DEVID_CHANGED</dt> | |||
<dd> | ||||
The client is using device ID notifications and the server | The client is using device ID notifications and the server | |||
has changed a device ID mapping held by the client. This | has changed a device ID mapping held by the client. This | |||
flag will stay present until the client has obtained the new | flag will stay present until the client has obtained the new | |||
mapping with GETDEVICEINFO. | mapping with GETDEVICEINFO. | |||
</t> | </dd> | |||
<t hangText="SEQ4_STATUS_DEVID_DELETED"><vspace /> | <dt>SEQ4_STATUS_DEVID_DELETED</dt> | |||
<dd> | ||||
The client is using device ID notifications and the server | The client is using device ID notifications and the server | |||
has deleted a device ID mapping held by the client. | has deleted a device ID mapping held by the client. | |||
This flag will stay in effect until the client sends a GETDEVICEINFO | This flag will stay in effect until the client sends a GETDEVICEINFO | |||
on the device ID with a null value in the argument gdia_notify_types. | on the device ID with a null value in the argument gdia_notify_types. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | <t> | |||
<t> | ||||
The value of the sa_sequenceid argument relative to | The value of the sa_sequenceid argument relative to | |||
the cached sequence ID on the slot falls into one | the cached sequence ID on the slot falls into one | |||
of three cases. | of three cases. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If the difference between sa_sequenceid and | If the difference between sa_sequenceid and | |||
the server's cached sequence ID at the slot ID | the server's cached sequence ID at the slot ID | |||
is two (2) or more, | is two (2) or more, | |||
or if sa_sequenceid is less | or if sa_sequenceid is less | |||
than the cached sequence ID (accounting | than the cached sequence ID (accounting | |||
for wraparound of the unsigned sequence ID value), | for wraparound of the unsigned sequence ID value), | |||
then the server MUST return NFS4ERR_SEQ_MISORDERED. | then the server <bcp14>MUST</bcp14> return NFS4ERR_SEQ_MISORDERED. | |||
</t> | </li> | |||
<t> | <li> | |||
If sa_sequenceid and the cached sequence ID are | If sa_sequenceid and the cached sequence ID are | |||
the same, this is a retry, and the server replies | the same, this is a retry, and the server replies | |||
with what is recorded in the reply | with what is recorded in the reply | |||
cache. | cache. | |||
The lease is possibly renewed as described below. | The lease is possibly renewed as described below. | |||
</t> | </li> | |||
<t> | <li> | |||
If sa_sequenceid is one greater (accounting for | If sa_sequenceid is one greater (accounting for | |||
wraparound) than the cached sequence ID, then | wraparound) than the cached sequence ID, then | |||
this is a new request, and the slot's sequence | this is a new request, and the slot's sequence | |||
ID is incremented. The operations subsequent to | ID is incremented. The operations subsequent to | |||
SEQUENCE, if any, are processed. If there are no | SEQUENCE, if any, are processed. If there are no | |||
other operations, the only other effects are to | other operations, the only other effects are to | |||
cache the SEQUENCE reply in the slot, maintain the | cache the SEQUENCE reply in the slot, maintain the | |||
session's activity, and possibly renew the lease. | session's activity, and possibly renew the lease. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
If the client reuses a slot ID and sequence ID for | If the client reuses a slot ID and sequence ID for | |||
a completely different request, the server MAY treat | a completely different request, the server <bcp14>MAY</bcp14> treat | |||
the request as if it is a retry of what it has already | the request as if it is a retry of what it has already | |||
executed. The server MAY however detect the client's | executed. The server <bcp14>MAY</bcp14> however detect the client's | |||
illegal reuse and return NFS4ERR_SEQ_FALSE_RETRY. | illegal reuse and return NFS4ERR_SEQ_FALSE_RETRY. | |||
</t> | </t> | |||
<t> | <t> | |||
If SEQUENCE returns an error, then the state of the | If SEQUENCE returns an error, then the state of the | |||
slot (sequence ID, cached reply) MUST NOT change, | slot (sequence ID, cached reply) <bcp14>MUST NOT</bcp14> change, | |||
and the associated lease MUST NOT be renewed. | and the associated lease <bcp14>MUST NOT</bcp14> be renewed. | |||
</t> | </t> | |||
<t> | <t> | |||
If SEQUENCE returns NFS4_OK, then the associated | If SEQUENCE returns NFS4_OK, then the associated | |||
lease MUST be renewed (see <xref target="lease_renewal"/>), | lease <bcp14>MUST</bcp14> be renewed (see <xref target="lease_renewal" form at="default"/>), | |||
except if SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED is | except if SEQ4_STATUS_EXPIRED_ALL_STATE_REVOKED is | |||
returned in sr_status_flags. | returned in sr_status_flags. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section toc="exclude" anchor="OP_SEQUENCE_IMPLEMENTATION" numbered="tru | |||
<section toc="exclude" anchor="OP_SEQUENCE_IMPLEMENTATION" title="IMPLEMENTATI | e"> | |||
ON"> | <name>IMPLEMENTATION</name> | |||
<t> | <t> | |||
The server MUST maintain a mapping of session ID to client ID | The server <bcp14>MUST</bcp14> maintain a mapping of session ID to client | |||
ID | ||||
in order to validate any operations that follow SEQUENCE | in order to validate any operations that follow SEQUENCE | |||
that take a stateid as an argument and/or result. | that take a stateid as an argument and/or result. | |||
</t> | </t> | |||
<t> | <t> | |||
If the client establishes a persistent session, then | If the client establishes a persistent session, then | |||
a SEQUENCE received after a server restart might encounter | a SEQUENCE received after a server restart might encounter | |||
requests performed and recorded in a persistent reply | requests performed and recorded in a persistent reply | |||
cache before the server restart. In this case, SEQUENCE | cache before the server restart. In this case, SEQUENCE | |||
will be processed successfully, while requests that | will be processed successfully, while requests that | |||
were not previously performed and recorded are rejected with | were not previously performed and recorded are rejected with | |||
NFS4ERR_DEADSESSION. | NFS4ERR_DEADSESSION. | |||
</t> | </t> | |||
<t> | <t> | |||
Depending on which of the operations within the COMPOUND were | Depending on which of the operations within the COMPOUND were | |||
successfully | successfully | |||
performed before the server restart, these operations will | performed before the server restart, these operations will | |||
also have replies sent from the server reply cache. | also have replies sent from the server reply cache. | |||
Note that when these operations establish locking state, it | Note that when these operations establish locking state, it | |||
is locking state that applies to the previous server instance | is locking state that applies to the previous server instance | |||
and to the previous client ID, even though the | and to the previous client ID, even though the | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_SET_SSV" numbered="true" toc="default"> | |||
$ --> | <name>Operation 54: SET_SSV - Update SSV for a Client ID</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_SET_SSV_ARGUMENT" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENT</name> | |||
<section anchor="OP_SET_SSV" | <sourcecode type="xdr"><![CDATA[ | |||
title="Operation 54: SET_SSV - Update SSV for a Client ID" > | ||||
<section toc="exclude" anchor="OP_SET_SSV_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_SET_SSV_RESULT" numbered="true"> | |||
</figure> | <name>RESULT</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_SET_SSV_RESULT" title="RESULT"> | ||||
<figure> | ||||
<artwork> | ||||
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: | |||
SET_SSV4resok ssr_resok4; | SET_SSV4resok ssr_resok4; | |||
default: | default: | |||
void; | void; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_SET_SSV_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_SET_SSV_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
This operation is used to update the | This operation is used to update the | |||
SSV for a client ID. Before SET_SSV is called the | SSV for a client ID. Before SET_SSV is called the | |||
first time on a client ID, the SSV is zero. | first time on a client ID, the SSV is zero. | |||
The SSV is the key used for the SSV GSS mechanism | The SSV is the key used for the SSV GSS mechanism | |||
(<xref target="ssv_mech" />) | (<xref target="ssv_mech" format="default"/>) | |||
</t> | </t> | |||
<t> | <t> | |||
SET_SSV MUST be preceded by a | SET_SSV <bcp14>MUST</bcp14> be preceded by a | |||
SEQUENCE operation in the same COMPOUND. | SEQUENCE operation in the same COMPOUND. | |||
It MUST NOT be used if the client | It <bcp14>MUST NOT</bcp14> be used if the client | |||
did not opt for SP4_SSV state protection when the | did not opt for SP4_SSV state protection when the | |||
client ID was created | client ID was created | |||
(see <xref target="OP_EXCHANGE_ID" />); | (see <xref target="OP_EXCHANGE_ID" format="default"/>); | |||
the server returns NFS4ERR_INVAL in that case. | the server returns NFS4ERR_INVAL in that case. | |||
</t> | </t> | |||
<t> | <t> | |||
The field ssa_digest is computed as the output of | The field ssa_digest is computed as the output of | |||
the HMAC (<xref target="RFC2104">RFC 2104</xref>) using the subkey derived | the HMAC (<xref target="RFC2104" format="default">RFC 2104</xref>) using t he subkey derived | |||
from the SSV4_SUBKEY_MIC_I2T and current SSV | from the SSV4_SUBKEY_MIC_I2T and current SSV | |||
as the key (see <xref target="ssv_mech" /> for a | as the key (see <xref target="ssv_mech" format="default"/> for a | |||
description of subkeys), and an XDR encoded value of data type ssa_digest_ input4. | description of subkeys), and an XDR encoded value of data type ssa_digest_ input4. | |||
The field sdi_seqargs is equal to the | The field sdi_seqargs is equal to the | |||
arguments of the SEQUENCE operation | arguments of the SEQUENCE operation | |||
for the COMPOUND procedure that | for the COMPOUND procedure that | |||
SET_SSV is within. | SET_SSV is within. | |||
</t> | </t> | |||
<t> | <t> | |||
The argument ssa_ssv | The argument ssa_ssv | |||
is XORed with the current SSV to produce | is XORed with the current SSV to produce | |||
the new SSV. The argument ssa_ssv SHOULD be generated randomly. | the new SSV. The argument ssa_ssv <bcp14>SHOULD</bcp14> be generated rando | |||
</t> | mly. | |||
<t> | </t> | |||
<t> | ||||
In the response, ssr_digest is the output of the HMAC using the | In the response, ssr_digest is the output of the HMAC using the | |||
subkey derived from SSV4_SUBKEY_MIC_T2I and new SSV as the key, | subkey derived from SSV4_SUBKEY_MIC_T2I and new SSV as the key, | |||
and an XDR encoded value of data type ssr_digest_input4. The | and an XDR encoded value of data type ssr_digest_input4. The | |||
field sdi_seqres is equal to the results of the SEQUENCE | field sdi_seqres is equal to the results of the SEQUENCE | |||
operation for the COMPOUND procedure that SET_SSV is within. | operation for the COMPOUND procedure that SET_SSV is within. | |||
</t> | </t> | |||
<t> | <t> | |||
As noted in <xref target="OP_EXCHANGE_ID" />, the client and | As noted in <xref target="OP_EXCHANGE_ID" format="default"/>, the client a | |||
nd | ||||
server can maintain multiple concurrent versions of the SSV. | server can maintain multiple concurrent versions of the SSV. | |||
The client and server each MUST maintain an internal | The client and server each <bcp14>MUST</bcp14> maintain an internal | |||
SSV version number, which is set to one the first time | SSV version number, which is set to one the first time | |||
SET_SSV executes on the server and the client | SET_SSV executes on the server and the client | |||
receives the first SET_SSV reply. Each subsequent | receives the first SET_SSV reply. Each subsequent | |||
SET_SSV increases the internal SSV version number by one. The | SET_SSV increases the internal SSV version number by one. The | |||
value of this version number corresponds to the smpt_ssv_seq, | value of this version number corresponds to the smpt_ssv_seq, | |||
smt_ssv_seq, sspt_ssv_seq, and ssct_ssv_seq fields of the | smt_ssv_seq, sspt_ssv_seq, and ssct_ssv_seq fields of the | |||
SSV GSS mechanism tokens (see <xref target="ssv_mech"/>). | SSV GSS mechanism tokens (see <xref target="ssv_mech" format="default"/>). | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_SET_SSV_IMPLEMENTATION" title="IMPLEMENTATIO | <section toc="exclude" anchor="OP_SET_SSV_IMPLEMENTATION" numbered="true | |||
N"> | "> | |||
<t> | <name>IMPLEMENTATION</name> | |||
When the server receives ssa_digest, it MUST verify the digest | <t> | |||
When the server receives ssa_digest, it <bcp14>MUST</bcp14> verify the dig | ||||
est | ||||
by computing the digest the same way the client did and | by computing the digest the same way the client did and | |||
comparing it with ssa_digest. If the server gets a different | comparing it with ssa_digest. If the server gets a different | |||
result, this is an error, NFS4ERR_BAD_SESSION_DIGEST. | result, this is an error, NFS4ERR_BAD_SESSION_DIGEST. | |||
This error might be the result of another SET_SSV from the | This error might be the result of another SET_SSV from the | |||
same client ID changing the SSV. If so, the client recovers | same client ID changing the SSV. If so, the client recovers | |||
by sending a SET_SSV operation again with a recomputed digest based on | by sending a SET_SSV operation again with a recomputed digest based on | |||
the subkey of the new SSV. If the transport connection is dropped after | the subkey of the new SSV. If the transport connection is dropped after | |||
the SET_SSV request is sent, but before the | the SET_SSV request is sent, but before the | |||
SET_SSV reply is received, then there are special considerations | SET_SSV reply is received, then there are special considerations | |||
for recovery if the client has no more connections associated | for recovery if the client has no more connections associated | |||
with sessions associated with the client ID of the SSV. See | with sessions associated with the client ID of the SSV. See | |||
<xref target="OP_BIND_CONN_TO_SESSION_IMPLEMENTATION"/>. | <xref target="OP_BIND_CONN_TO_SESSION_IMPLEMENTATION" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
Clients SHOULD NOT send an ssa_ssv that is equal to a previous | Clients <bcp14>SHOULD NOT</bcp14> send an ssa_ssv that is equal to a previ | |||
ous | ||||
ssa_ssv, nor equal to a previous or current SSV (including an ssa_ssv equa l to zero | ssa_ssv, nor equal to a previous or current SSV (including an ssa_ssv equa l to zero | |||
since the SSV is initialized to zero when the client ID is created). | since the SSV is initialized to zero when the client ID is created). | |||
</t> | </t> | |||
<t> | <t> | |||
Clients SHOULD send SET_SSV with RPCSEC_GSS privacy. Servers | Clients <bcp14>SHOULD</bcp14> send SET_SSV with RPCSEC_GSS privacy. Server | |||
MUST support RPCSEC_GSS with privacy for any COMPOUND that has { | s | |||
<bcp14>MUST</bcp14> support RPCSEC_GSS with privacy for any COMPOUND that | ||||
has { | ||||
SEQUENCE, SET_SSV }. | SEQUENCE, SET_SSV }. | |||
</t> | </t> | |||
<t> | <t> | |||
A client SHOULD NOT send SET_SSV with the SSV GSS | A client <bcp14>SHOULD NOT</bcp14> send SET_SSV with the SSV GSS | |||
mechanism's credential because the purpose of SET_SSV | mechanism's credential because the purpose of SET_SSV | |||
is to seed the SSV from non-SSV credentials. Instead, | is to seed the SSV from non-SSV credentials. Instead, | |||
SET_SSV SHOULD be sent with the credential of | SET_SSV <bcp14>SHOULD</bcp14> be sent with the credential of | |||
a user that is accessing the client ID for the | a user that is accessing the client ID for the | |||
first time | first time | |||
(<xref target="protect_state_change" />). | (<xref target="protect_state_change" format="default"/>). | |||
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> | <section anchor="OP_TEST_STATEID" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 55: TEST_STATEID - Test Stateids for Validity</name> | |||
$ --> | <section toc="exclude" anchor="OP_TEST_STATEID_ARGUMENT" numbered="true" | |||
<!-- Copyright (C) The IETF Trust (2007) --> | > | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENT</name> | |||
<section anchor="OP_TEST_STATEID" title="Operation 55: TEST_STATEID - Test State | <sourcecode type="xdr"><![CDATA[ | |||
ids for Validity" > | ||||
<section toc="exclude" anchor="OP_TEST_STATEID_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
struct TEST_STATEID4args { | struct TEST_STATEID4args { | |||
stateid4 ts_stateids<>; | stateid4 ts_stateids<>; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_TEST_STATEID_RESULT" numbered="true"> | |||
</figure> | <name>RESULT</name> | |||
</section> | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_TEST_STATEID_RESULT" title="RESULT"> | ||||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_TEST_STATEID4_DESCRIPTION" numbered="t | |||
</figure> | rue"> | |||
</section> | <name>DESCRIPTION</name> | |||
<section toc="exclude" anchor="OP_TEST_STATEID4_DESCRIPTION" title="DESCRIPTIO | <t> | |||
N"> | ||||
<t> | ||||
The TEST_STATEID operation is used to check the validity of | The TEST_STATEID operation is used to check the validity of | |||
a set of stateids. It can be used at any time, but the client | a set of stateids. It can be used at any time, but the client | |||
should definitely use it when it | should definitely use it when it | |||
receives an indication that one or more of its stateids have been | receives an indication that one or more of its stateids have been | |||
invalidated due to lock revocation. This occurs when the SEQUENCE | invalidated due to lock revocation. This occurs when the SEQUENCE | |||
operation returns with one of the following sr_status_flags set: | operation returns with one of the following sr_status_flags set: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED | SEQ4_STATUS_EXPIRED_SOME_STATE_REVOKED | |||
</t> | </li> | |||
<t> | <li> | |||
SEQ4_STATUS_EXPIRED_ADMIN_STATE_REVOKED | SEQ4_STATUS_EXPIRED_ADMIN_STATE_REVOKED | |||
</t> | </li> | |||
<t> | <li> | |||
SEQ4_STATUS_EXPIRED_RECALLABLE_STATE_REVOKED | SEQ4_STATUS_EXPIRED_RECALLABLE_STATE_REVOKED | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The client can use TEST_STATEID one or more times to test the | The client can use TEST_STATEID one or more times to test the | |||
validity of its stateids. Each use of TEST_STATEID allows a large | validity of its stateids. Each use of TEST_STATEID allows a large | |||
set of such stateids to be tested and avoids problems with earlier | set of such stateids to be tested and avoids problems with earlier | |||
stateids in a COMPOUND request from interfering with the checking of | stateids in a COMPOUND request from interfering with the checking of | |||
subsequent stateids, as would happen if individual stateids were | subsequent stateids, as would happen if individual stateids were | |||
tested by a series of corresponding by operations in a COMPOUND | tested by a series of corresponding by operations in a COMPOUND | |||
request. | request. | |||
</t> | </t> | |||
<t> | <t> | |||
For each stateid, the server returns the status code that | For each stateid, the server returns the status code that | |||
would be returned if that stateid were to be used in normal | would be returned if that stateid were to be used in normal | |||
operation. Returning such a status indication is not an | operation. Returning such a status indication is not an | |||
error and does not cause COMPOUND processing to terminate. Checks | error and does not cause COMPOUND processing to terminate. Checks | |||
for the validity of the stateid proceed as they would for | for the validity of the stateid proceed as they would for | |||
normal operations with a number of exceptions: | normal operations with a number of exceptions: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
There is no check for the type of stateid object, as would be | There is no check for the type of stateid object, as would be | |||
the case for normal use of a stateid. | the case for normal use of a stateid. | |||
</t> | </li> | |||
<t> | <li> | |||
There is no reference to the current filehandle. | There is no reference to the current filehandle. | |||
</t> | </li> | |||
<t> | <li> | |||
Special stateids are always considered invalid (they result | Special stateids are always considered invalid (they result | |||
in the error code NFS4ERR_BAD_STATEID). | in the error code NFS4ERR_BAD_STATEID). | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
All stateids are interpreted as being associated with the client | All stateids are interpreted as being associated with the client | |||
for the current session. Any possible association with a previous | for the current session. Any possible association with a previous | |||
instance of the client (as stale stateids) is not considered. | instance of the client (as stale stateids) is not considered. | |||
</t> | </t> | |||
<t> | <t> | |||
The valid status values in the returned status_code array | The valid status values in the returned status_code array | |||
are NFS4ERR_OK, NFS4ERR_BAD_STATEID, NFS4ERR_OLD_STATEID, | are NFS4ERR_OK, NFS4ERR_BAD_STATEID, NFS4ERR_OLD_STATEID, | |||
NFS4ERR_EXPIRED, NFS4ERR_ADMIN_REVOKED, and NFS4ERR_DELEG_REVOKED. | NFS4ERR_EXPIRED, NFS4ERR_ADMIN_REVOKED, and NFS4ERR_DELEG_REVOKED. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_TEST_STATEID_IMPLEMENTATION" title="IMPLEMEN | <section toc="exclude" anchor="OP_TEST_STATEID_IMPLEMENTATION" numbered= | |||
TATION"> | "true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
See Sections <xref target="stateid_structure" format="counter" /> and | <t> | |||
<xref target="stateid_lifetime" format="counter" /> | See Sections <xref target="stateid_structure" format="counter"/> and | |||
<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> | |||
<section anchor="OP_WANT_DELEGATION" numbered="true" toc="default"> | ||||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 56: WANT_DELEGATION - Request Delegation</name> | |||
$ --> | <section toc="exclude" anchor="OP_WANT_DELEGATION_ARGUMENT" numbered="tr | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | ue"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENT</name> | |||
<section anchor="OP_WANT_DELEGATION" | <sourcecode type="xdr"><![CDATA[ | |||
title="Operation 56: WANT_DELEGATION - Request Delegation" > | ||||
<section toc="exclude" anchor="OP_WANT_DELEGATION_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
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 39699 ¶ | skipping to change at line 39643 ¶ | |||
* Used during server reclaim grace period. | * Used during server reclaim grace period. | |||
*/ | */ | |||
case CLAIM_PREVIOUS: | case CLAIM_PREVIOUS: | |||
/* CURRENT_FH: object being reclaimed */ | /* CURRENT_FH: object being reclaimed */ | |||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_WANT_DELEGATION_RESULT" numbered="true | |||
</figure> | "> | |||
</section> | <name>RESULT</name> | |||
<section toc="exclude" anchor="OP_WANT_DELEGATION_RESULT" title="RESULT"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
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> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_WANT_DELEGATION_DESCRIPTION" numbered= | |||
</figure> | "true"> | |||
</section> | <name>DESCRIPTION</name> | |||
<section toc="exclude" anchor="OP_WANT_DELEGATION_DESCRIPTION" title="DESCRIPT | <t> | |||
ION"> | ||||
<t> | ||||
Where this description mandates the return of a specific error | Where this description mandates the return of a specific error | |||
code for a specific condition, and where multiple conditions | code for a specific condition, and where multiple conditions | |||
apply, the server MAY return any of the mandated error codes. | apply, the server <bcp14>MAY</bcp14> return any of the mandated error code | |||
</t> | s. | |||
<t> | </t> | |||
<t> | ||||
This operation allows a client to: | This operation allows a client to: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Get a delegation on all types | Get a delegation on all types | |||
of files except directories. | of files except directories. | |||
</t> | </li> | |||
<t> | <li> | |||
Register a "want" for a delegation for the | Register a "want" for a delegation for the | |||
specified file object, and be notified via a | specified file object, and be notified via a | |||
callback when the delegation is available. The | callback when the delegation is available. The | |||
server MAY support notifications of availability | server <bcp14>MAY</bcp14> support notifications of availability | |||
via callbacks. If the server does not support | via callbacks. If the server does not support | |||
registration of wants, it MUST NOT return | registration of wants, it <bcp14>MUST NOT</bcp14> return | |||
an error to indicate that, and instead MUST | an error to indicate that, and instead <bcp14>MUST</bcp14> | |||
return with ond_why set to WND4_CONTENTION or | return with ond_why set to WND4_CONTENTION or | |||
WND4_RESOURCE and ond_server_will_push_deleg or | WND4_RESOURCE and ond_server_will_push_deleg or | |||
ond_server_will_signal_avail set to FALSE. When the | ond_server_will_signal_avail set to FALSE. When the | |||
server indicates that it will notify the client | server indicates that it will notify the client | |||
by means of a callback, it will either provide | by means of a callback, it will either provide | |||
the delegation using a CB_PUSH_DELEG operation or | the delegation using a CB_PUSH_DELEG operation or | |||
cancel its promise by sending a CB_WANTS_CANCELLED | cancel its promise by sending a CB_WANTS_CANCELLED | |||
operation. | operation. | |||
</t> | </li> | |||
<t> | <li> | |||
Cancel a want for a delegation. | Cancel a want for a delegation. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | The client <bcp14>SHOULD NOT</bcp14> set OPEN4_SHARE_ACCESS_READ and <bcp1 | |||
The client SHOULD NOT set OPEN4_SHARE_ACCESS_READ and SHOULD NOT | 4>SHOULD NOT</bcp14> | |||
set OPEN4_SHARE_ACCESS_WRITE in wda_want. If it does, the server | set OPEN4_SHARE_ACCESS_WRITE in wda_want. If it does, the server | |||
MUST ignore them. | <bcp14>MUST</bcp14> ignore them. | |||
</t> | </t> | |||
<t> | <t> | |||
The meanings of the following flags in wda_want are the same as | The meanings of the following flags in wda_want are the same as | |||
they are in OPEN, except as noted below. | they are in OPEN, except as noted below. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
OPEN4_SHARE_ACCESS_WANT_READ_DELEG | OPEN4_SHARE_ACCESS_WANT_READ_DELEG | |||
</t> | </li> | |||
<t> | <li> | |||
OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG | OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG | |||
</t> | </li> | |||
<t> | <li> | |||
OPEN4_SHARE_ACCESS_WANT_ANY_DELEG | OPEN4_SHARE_ACCESS_WANT_ANY_DELEG | |||
</t> | </li> | |||
<t> | <li> | |||
OPEN4_SHARE_ACCESS_WANT_NO_DELEG. Unlike the OPEN operation, | OPEN4_SHARE_ACCESS_WANT_NO_DELEG. Unlike the OPEN operation, | |||
this flag SHOULD NOT be set by the client in the arguments to | this flag <bcp14>SHOULD NOT</bcp14> be set by the client in the argume | |||
WANT_DELEGATION, and MUST be ignored by the server. | nts to | |||
WANT_DELEGATION, and <bcp14>MUST</bcp14> be ignored by the server. | ||||
</t> | </li> | |||
<t> | <li> | |||
OPEN4_SHARE_ACCESS_WANT_CANCEL | OPEN4_SHARE_ACCESS_WANT_CANCEL | |||
</t> | </li> | |||
<t> | <li> | |||
OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL | OPEN4_SHARE_ACCESS_WANT_SIGNAL_DELEG_WHEN_RESRC_AVAIL | |||
</t> | </li> | |||
<t> | <li> | |||
OPEN4_SHARE_ACCESS_WANT_PUSH_DELEG_WHEN_UNCONTENDED | OPEN4_SHARE_ACCESS_WANT_PUSH_DELEG_WHEN_UNCONTENDED | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
The handling of the above flags in WANT_DELEGATION is the same | The handling of the above flags in WANT_DELEGATION is the same | |||
as in OPEN. Information about the delegation and/or the | as in OPEN. Information about the delegation and/or the | |||
promises the server is making regarding future callbacks are | promises the server is making regarding future callbacks are | |||
the same as those described in the open_delegation4 structure. | the same as those described in the open_delegation4 structure. | |||
</t> | </t> | |||
<t> | <t> | |||
The successful results of WANT_DELEGATION are of data type | The successful results of WANT_DELEGATION are of data type | |||
open_delegation4, which is the same data type as the "delegation" | open_delegation4, which is the same data type as the "delegation" | |||
field in the results of the OPEN operation | field in the results of the OPEN operation | |||
(see <xref target="OP_OPEN_DESCRIPTION" />). | (see <xref target="OP_OPEN_DESCRIPTION" format="default"/>). | |||
The server constructs wdr_resok4 the same way it constructs | The server constructs wdr_resok4 the same way it constructs | |||
OPEN's "delegation" with one difference: | OPEN's "delegation" with one difference: | |||
WANT_DELEGATION MUST NOT return a delegation type of | WANT_DELEGATION <bcp14>MUST NOT</bcp14> return a delegation type of | |||
OPEN_DELEGATE_NONE. | OPEN_DELEGATE_NONE. | |||
</t> | </t> | |||
<t> | <t> | |||
If ((wda_want & OPEN4_SHARE_ACCESS_WANT_DELEG_MASK) & | If ((wda_want & OPEN4_SHARE_ACCESS_WANT_DELEG_MASK) & | |||
~OPEN4_SHARE_ACCESS_WANT_NO_DELEG) is zero, | ~OPEN4_SHARE_ACCESS_WANT_NO_DELEG) is zero, | |||
then the client is indicating no | then the client is indicating no | |||
explicit desire or non-desire for a delegation and the server MUST return | explicit desire or non-desire for a delegation and the server <bcp14>MUST< /bcp14> return | |||
NFS4ERR_INVAL. | NFS4ERR_INVAL. | |||
</t> | </t> | |||
<t> | <t> | |||
The client uses the | The client uses the | |||
OPEN4_SHARE_ACCESS_WANT_CANCEL | OPEN4_SHARE_ACCESS_WANT_CANCEL | |||
flag in the WANT_DELEGATION | flag in the WANT_DELEGATION | |||
operation to cancel a previously requested want for a delegation. | operation to cancel a previously requested want for a delegation. | |||
Note that if the server is in the process of sending the | Note that if the server is in the process of sending the | |||
delegation (via CB_PUSH_DELEG) at the time the client sends | delegation (via CB_PUSH_DELEG) at the time the client sends | |||
a cancellation of the want, the delegation might still be pushed | a cancellation of the want, the delegation might still be pushed | |||
to the client. | to the client. | |||
</t> | </t> | |||
<t> | <t> | |||
If WANT_DELEGATION fails to return a delegation, and | If WANT_DELEGATION fails to return a delegation, and | |||
the server returns NFS4_OK, the server MUST set the | the server returns NFS4_OK, the server <bcp14>MUST</bcp14> set the | |||
delegation type to OPEN4_DELEGATE_NONE_EXT, and set | delegation type to OPEN4_DELEGATE_NONE_EXT, and set | |||
od_whynone, as described in <xref target="OP_OPEN" | od_whynone, as described in <xref target="OP_OPEN" format="default"/>. Wri | |||
/>. Write delegations are not available for | te delegations are not available for | |||
file types that are not writable. This includes | file types that are not writable. This includes | |||
file objects of types NF4BLK, NF4CHR, NF4LNK, | file objects of types NF4BLK, NF4CHR, NF4LNK, | |||
NF4SOCK, and NF4FIFO. If the client requests | NF4SOCK, and NF4FIFO. If the client requests | |||
OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG without | OPEN4_SHARE_ACCESS_WANT_WRITE_DELEG without | |||
OPEN4_SHARE_ACCESS_WANT_READ_DELEG on an object with | OPEN4_SHARE_ACCESS_WANT_READ_DELEG on an object with | |||
one of the aforementioned file types, the server must | one of the aforementioned file types, the server must | |||
set wdr_resok4.od_whynone.ond_why to | set wdr_resok4.od_whynone.ond_why to | |||
WND4_WRITE_DELEG_NOT_SUPP_FTYPE. | WND4_WRITE_DELEG_NOT_SUPP_FTYPE. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_WANT_DELEGATION_IMPLEMENTATION" title="IMPLE | <section toc="exclude" anchor="OP_WANT_DELEGATION_IMPLEMENTATION" number | |||
MENTATION"> | ed="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
A request for a conflicting delegation is not normally intended to trigger | A request for a conflicting delegation is not normally intended to trigger | |||
the recall of the existing delegation. Servers may choose to treat | the recall of the existing delegation. Servers may choose to treat | |||
some clients as having higher priority such that their wants will | some clients as having higher priority such that their wants will | |||
trigger recall of an existing delegation, although that is expected | trigger recall of an existing delegation, although that is expected | |||
to be an unusual situation. | to be an unusual situation. | |||
</t> | </t> | |||
<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> | <section anchor="OP_DESTROY_CLIENTID" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 57: DESTROY_CLIENTID - Destroy a Client ID</name> | |||
$ --> | <section toc="exclude" anchor="OP_DESTROY_CLIENTID_ARGUMENT" numbered="t | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | rue"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENT</name> | |||
<section anchor="OP_DESTROY_CLIENTID" title="Operation 57: DESTROY_CLIENTID - De | <sourcecode type="xdr"><![CDATA[ | |||
stroy a Client ID" > | ||||
<section toc="exclude" anchor="OP_DESTROY_CLIENTID_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
struct DESTROY_CLIENTID4args { | struct DESTROY_CLIENTID4args { | |||
clientid4 dca_clientid; | clientid4 dca_clientid; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_DESTROY_CLIENTID_RESULT" numbered="tru | |||
</figure> | e"> | |||
</section> | <name>RESULT</name> | |||
<section toc="exclude" anchor="OP_DESTROY_CLIENTID_RESULT" title="RESULT"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
struct DESTROY_CLIENTID4res { | struct DESTROY_CLIENTID4res { | |||
nfsstat4 dcr_status; | nfsstat4 dcr_status; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_DESTROY_CLIENTID_DESCRIPTION" numbered | |||
</figure> | ="true"> | |||
</section> | <name>DESCRIPTION</name> | |||
<section toc="exclude" anchor="OP_DESTROY_CLIENTID_DESCRIPTION" title="DESCRIP | <t> | |||
TION"> | ||||
<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, | |||
and/or wants (<xref target="OP_WANT_DELEGATION" />) | and/or wants (<xref target="OP_WANT_DELEGATION" format="default"/>) | |||
associated with the unexpired lease of the client | associated with the unexpired lease of the client | |||
ID, the server MUST return NFS4ERR_CLIENTID_BUSY. | ID, the server <bcp14>MUST</bcp14> return NFS4ERR_CLIENTID_BUSY. | |||
DESTROY_CLIENTID MAY be preceded with a SEQUENCE | DESTROY_CLIENTID <bcp14>MAY</bcp14> be preceded with a SEQUENCE | |||
operation as long as the client ID derived from the | operation as long as the client ID derived from the | |||
session ID of SEQUENCE is not the same as the client | session ID of SEQUENCE is not the same as the client | |||
ID to be destroyed. If the client IDs are the same, | ID to be destroyed. If the client IDs are the same, | |||
then the server MUST return NFS4ERR_CLIENTID_BUSY. | then the server <bcp14>MUST</bcp14> return NFS4ERR_CLIENTID_BUSY. | |||
</t> | ||||
<t> | </t> | |||
<t> | ||||
If DESTROY_CLIENTID is not prefixed by SEQUENCE, | If DESTROY_CLIENTID is not prefixed by SEQUENCE, | |||
it MUST be the only operation in the COMPOUND | it <bcp14>MUST</bcp14> be the only operation in the COMPOUND | |||
request (otherwise, the server MUST return | request (otherwise, the server <bcp14>MUST</bcp14> return | |||
NFS4ERR_NOT_ONLY_OP). If the operation is sent | NFS4ERR_NOT_ONLY_OP). If the operation is sent | |||
without a SEQUENCE preceding it, a client that | without a SEQUENCE preceding it, a client that | |||
retransmits the request may receive an error in | retransmits the request may receive an error in | |||
response, because the original request might have | response, because the original request might have | |||
been successfully executed. | been successfully executed. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_DESTROY_CLIENTID_IMPLEMENTATION" title="IMPL | <section toc="exclude" anchor="OP_DESTROY_CLIENTID_IMPLEMENTATION" numbe | |||
EMENTATION"> | red="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_RECLAIM_COMPLETE" numbered="true" toc="default"> | |||
$ --> | <name>Operation 58: RECLAIM_COMPLETE - Indicates Reclaims Finished</name | |||
<!-- Copyright (C) The IETF Trust (2007) --> | > | |||
<!-- Copyright (C) The Internet Society (2006) --> | <section toc="exclude" anchor="OP_RECLAIM_COMPLETE_ARGUMENT" numbered="t | |||
<section title="Operation 58: RECLAIM_COMPLETE - Indicates Reclaims Finished | rue"> | |||
" | <name>ARGUMENT</name> | |||
anchor="OP_RECLAIM_COMPLETE"> | <sourcecode type="xdr"><![CDATA[ | |||
<section title="ARGUMENT" | ||||
toc="exclude" | ||||
anchor="OP_RECLAIM_COMPLETE_ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
<CODE BEGINS> | ||||
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> | ||||
<CODE ENDS> | </section> | |||
</artwork> | <section toc="exclude" anchor="OP_RECLAIM_COMPLETE_RESULTS" numbered="tr | |||
</figure> | ue"> | |||
</section> | <name>RESULTS</name> | |||
<sourcecode type="xdr"><![CDATA[ | ||||
<section title="RESULTS" | ||||
toc="exclude" | ||||
anchor="OP_RECLAIM_COMPLETE_RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
<CODE BEGINS> | ||||
struct RECLAIM_COMPLETE4res { | struct RECLAIM_COMPLETE4res { | |||
nfsstat4 rcr_status; | nfsstat4 rcr_status; | |||
}; | }; | |||
]]></sourcecode> | ||||
<CODE ENDS> | </section> | |||
</artwork> | <section toc="exclude" anchor="OP_RECLAIM_COMPLETE_DESCRIPTION" numbered | |||
</figure> | ="true"> | |||
</section> | <name>DESCRIPTION</name> | |||
<t> | ||||
<section title="DESCRIPTION" | ||||
toc="exclude" | ||||
anchor="OP_RECLAIM_COMPLETE_DESCRIPTION"> | ||||
<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 | |||
reclaim, | reclaim, | |||
when it is recovering state due to either a server restart or the | when it is recovering state due to either a server restart or the | |||
migration of a file system to another server. There are two types | migration of a file system to another server. There are two types | |||
of RECLAIM_COMPLETE operations: | of RECLAIM_COMPLETE operations: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
When rca_one_fs is FALSE, a global RECLAIM_COMPLETE is being | When rca_one_fs is FALSE, a global RECLAIM_COMPLETE is being | |||
done. This indicates that recovery of all | done. This indicates that recovery of all | |||
locks that the client held on the previous server instance | locks that the client held on the previous server instance | |||
has been completed. The current filehandle need not be set in | has been completed. The current filehandle need not be set in | |||
this case. | this case. | |||
</t> | </li> | |||
<t> | <li> | |||
When rca_one_fs is TRUE, a file system-specific RECLAIM_COMPLETE | When rca_one_fs is TRUE, a file system-specific RECLAIM_COMPLETE | |||
is being done. This indicates that recovery of locks | is being done. This indicates that recovery of locks | |||
for a single fs (the one designated by the current filehandle) | for a single fs (the one designated by the current filehandle) | |||
due to the migration of the file system has been completed. Presence | due to the migration of the file system has been completed. Presence | |||
of a current filehandle is required when rca_one_fs is set to TRUE. | of a current filehandle is required when rca_one_fs is set to TRUE. | |||
When the current filehandle designates a filehandle in a file system | When the current filehandle designates a filehandle in a file system | |||
not in the process of migration, the operation returns NFS4_OK and | not in the process of migration, the operation returns NFS4_OK and | |||
is otherwise ignored. | is otherwise ignored. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Once a RECLAIM_COMPLETE is done, there can be no further | Once a RECLAIM_COMPLETE is done, there can be no further | |||
reclaim operations for locks whose scope is defined as having | reclaim operations for locks whose scope is defined as having | |||
completed recovery. Once the client sends RECLAIM_COMPLETE, | completed recovery. Once the client sends RECLAIM_COMPLETE, | |||
the server will not allow the client to do | the server will not allow the client to do | |||
subsequent reclaims of locking state for that scope | subsequent reclaims of locking state for that scope | |||
and, if these are attempted, will return NFS4ERR_NO_GRACE. | and, if these are attempted, will return NFS4ERR_NO_GRACE. | |||
</t> | </t> | |||
<t> | <t> | |||
Whenever a client establishes a new client ID and before it does | Whenever a client establishes a new client ID and before it does | |||
the first non-reclaim operation that obtains a lock, it MUST send a | the first non-reclaim operation that obtains a lock, it <bcp14>MUST</bcp14 > send a | |||
RECLAIM_COMPLETE with rca_one_fs set to FALSE, even if there | RECLAIM_COMPLETE with rca_one_fs set to FALSE, even if there | |||
are no locks to | are no locks to | |||
reclaim. If non-reclaim | reclaim. If non-reclaim | |||
locking operations are done before the RECLAIM_COMPLETE, an NFS4ERR_GRACE | locking operations are done before the RECLAIM_COMPLETE, an NFS4ERR_GRACE | |||
error will be returned. | error will be returned. | |||
</t> | </t> | |||
<t> | <t> | |||
Similarly, when the client accesses a migrated file system on a new | Similarly, when the client accesses a migrated file system on a new | |||
server, before it sends the first non-reclaim operation that | server, before it sends the first non-reclaim operation that | |||
obtains a lock on this new server, it MUST send a RECLAIM_COMPLETE | obtains a lock on this new server, it <bcp14>MUST</bcp14> send a RECLAIM_C OMPLETE | |||
with rca_one_fs set to TRUE and current filehandle within that file system , | with rca_one_fs set to TRUE and current filehandle within that file system , | |||
even if there are no locks to reclaim. If non-reclaim locking | even if there are no locks to reclaim. If non-reclaim locking | |||
operations are done on that file system before the | operations are done on that file system before the | |||
RECLAIM_COMPLETE, an NFS4ERR_GRACE error will be returned. | RECLAIM_COMPLETE, an NFS4ERR_GRACE error will be returned. | |||
</t> | </t> | |||
<t> | <t> | |||
It should be noted that there are situations in which a client needs | It should be noted that there are situations in which a client needs | |||
to issue both forms of RECLAIM_COMPLETE. An example is an instance | to issue both forms of RECLAIM_COMPLETE. An example is an instance | |||
of file system migration in which the file system is migrated to a | of file system migration in which the file system is migrated to a | |||
server for which the client has no clientid. As a result, the client | server for which the client has no clientid. As a result, the client | |||
needs to obtain a clientid from the server (incurring the responsibility | needs to obtain a clientid from the server (incurring the responsibility | |||
to do RECLAIM_COMPLETE with rca_one_fs set to FALSE) as well as | to do RECLAIM_COMPLETE with rca_one_fs set to FALSE) as well as | |||
RECLAIM_COMPLETE with rca_one_fs set to TRUE to complete the per-fs | RECLAIM_COMPLETE with rca_one_fs set to TRUE to complete the per-fs | |||
grace period associated with the file system migration. These two | grace period associated with the file system migration. These two | |||
may be done in any order as long as all necessary lock reclaims | may be done in any order as long as all necessary lock reclaims | |||
have been done before | have been done before | |||
issuing either of them. | issuing either of them. | |||
</t> | </t> | |||
<t> | <t> | |||
Any locks not reclaimed at the point at which RECLAIM_COMPLETE | Any locks not reclaimed at the point at which RECLAIM_COMPLETE | |||
is done become non-reclaimable. The client MUST NOT attempt | is done become non-reclaimable. The client <bcp14>MUST NOT</bcp14> attemp t | |||
to reclaim them, either during | to reclaim them, either during | |||
the current server instance or in any subsequent | the current server instance or in any subsequent | |||
server instance, or on another server to which responsibility | server instance, or on another server to which responsibility | |||
for that file system is transferred. If the client were to do so, | for that file system is transferred. If the client were to do so, | |||
it would be | it would be | |||
violating the protocol by representing itself as owning locks | violating the protocol by representing itself as owning locks | |||
that it does not own, and so has no right to reclaim. See | that it does not own, and so has no right to reclaim. See | |||
Section 8.4.3 of <xref target="RFC5661"/> for a | <xref target="RFC5661" sectionFormat="of" section="8.4.3"/> for a | |||
discussion of edge conditions related to lock reclaim. | discussion of edge conditions related to lock reclaim. | |||
</t> | </t> | |||
<t> | <t> | |||
By sending a RECLAIM_COMPLETE, the client indicates readiness | By sending a RECLAIM_COMPLETE, the client indicates readiness | |||
to proceed to do normal non-reclaim locking operations. The client | to proceed to do normal non-reclaim locking operations. The client | |||
should be aware that such operations may temporarily result in | should be aware that such operations may temporarily result in | |||
NFS4ERR_GRACE errors until the server is ready to terminate its | NFS4ERR_GRACE errors until the server is ready to terminate its | |||
grace period. | grace period. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="IMPLEMENTATION" | <section toc="exclude" anchor="OP_RECLAIM_COMPLETE_IMPLEMENTATION" numbe | |||
toc="exclude" | red="true"> | |||
anchor="OP_RECLAIM_COMPLETE_IMPLEMENTATION"> | <name>IMPLEMENTATION</name> | |||
<t> | <t> | |||
Servers will typically use the information as to when reclaim | Servers will typically use the information as to when reclaim | |||
activity is complete to reduce the length of the grace period. | activity is complete to reduce the length of the grace period. | |||
When the server maintains in persistent storage | When the server maintains in persistent storage | |||
a list of clients that might have had locks, | a list of clients that might have had locks, | |||
it is able to use the fact that | it is able to use the fact that | |||
all such clients have done a RECLAIM_COMPLETE to terminate the | all such clients have done a RECLAIM_COMPLETE to terminate the | |||
grace period and begin normal operations (i.e., grant requests | grace period and begin normal operations (i.e., grant requests | |||
for new locks) sooner than it might otherwise. | for new locks) sooner than it might otherwise. | |||
</t> | </t> | |||
<t> | <t> | |||
Latency can be minimized by doing a RECLAIM_COMPLETE as part of | Latency can be minimized by doing a RECLAIM_COMPLETE as part of | |||
the COMPOUND request in which the last lock-reclaiming operation | the COMPOUND request in which the last lock-reclaiming operation | |||
is done. When there are no reclaims to be done, RECLAIM_COMPLETE | is done. When there are no reclaims to be done, RECLAIM_COMPLETE | |||
should be done immediately in order to allow the grace period | should be done immediately in order to allow the grace period | |||
to end as soon as possible. | to end as soon as possible. | |||
</t> | </t> | |||
<t> | <t> | |||
RECLAIM_COMPLETE should only be done once for each server instance | RECLAIM_COMPLETE should only be done once for each server instance | |||
or occasion of the transition of a file system. | or occasion of the transition of a file system. | |||
If it is done a second time, the error NFS4ERR_COMPLETE_ALREADY will | If it is done a second time, the error NFS4ERR_COMPLETE_ALREADY will | |||
result. Note that because of the session feature's retry protection, | result. Note that because of the session feature's retry protection, | |||
retries of COMPOUND | retries of COMPOUND | |||
requests containing RECLAIM_COMPLETE operation will not result | requests containing RECLAIM_COMPLETE operation will not result | |||
in this error. | in this error. | |||
</t> | </t> | |||
<t> | <t> | |||
When a RECLAIM_COMPLETE is sent, the client effectively acknowledges | When a RECLAIM_COMPLETE is sent, the client effectively acknowledges | |||
any locks not yet reclaimed as lost. This allows the server to | any locks not yet reclaimed as lost. This allows the server to | |||
re-enable the client to recover locks if the occurrence of edge | re-enable the client to recover locks if the occurrence of edge | |||
conditions, as described in | conditions, as described in | |||
<xref target="network_partitions_and_recovery"/>, | <xref target="network_partitions_and_recovery" format="default"/>, | |||
had caused the server to disable the client's ability to | had caused the server to disable the client's ability to | |||
recover locks. | recover locks. | |||
</t> | </t> | |||
<t> | <t> | |||
Because previous descriptions of RECLAIM_COMPLETE were not | Because previous descriptions of RECLAIM_COMPLETE were not | |||
sufficiently explicit about the circumstances in which use of | sufficiently explicit about the circumstances in which use of | |||
RECLAIM_COMPLETE with rca_one_fs set to TRUE was appropriate, | RECLAIM_COMPLETE with rca_one_fs set to TRUE was appropriate, | |||
there have been cases which it has been misused by clients who | there have been cases in which it has been misused by clients who | |||
have issued RECLAIM_COMPLETE with rca_one_fs set to TRUE when it | have issued RECLAIM_COMPLETE with rca_one_fs set to TRUE when it | |||
should have not been. There have also been | should have not been. There have also been | |||
cases in which servers have, in various ways, not responded to | cases in which servers have, in various ways, not responded to | |||
such misuse as described above, either ignoring the rca_one_fs | such misuse as described above, either ignoring the rca_one_fs | |||
setting (treating the operation as a global RECLAIM_COMPLETE) or | setting (treating the operation as a global RECLAIM_COMPLETE) or | |||
ignoring the entire operation. | ignoring the entire operation. | |||
</t> | </t> | |||
<t> | <t> | |||
While clients SHOULD NOT misuse | While clients <bcp14>SHOULD NOT</bcp14> misuse | |||
this feature and servers SHOULD respond to such misuse as described | this feature, and servers <bcp14>SHOULD</bcp14> respond to such misuse as | |||
above, implementers need to be aware of the following considerations | described | |||
as they make necessary tradeoffs between interoperability with | above, implementors need to be aware of the following considerations | |||
as they make necessary trade-offs between interoperability with | ||||
existing implementations and proper support for facilities to | existing implementations and proper support for facilities to | |||
allow lock recovery in the event of file system migration. | allow lock recovery in the event of file system migration. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
When servers have no support for becoming the destination server | When servers have no support for becoming the destination server | |||
of a file system subject to migration, there is no possibility of | of a file system subject to migration, there is no possibility of | |||
a per-fs RECLAIM_COMPLETE being done legitimately and occurrences of it | a per-fs RECLAIM_COMPLETE being done legitimately, and occurrences of it | |||
SHOULD be ignored. However, the negative consequences of accepting | <bcp14>SHOULD</bcp14> be ignored. However, the negative consequences of | |||
accepting | ||||
such mistaken use are quite limited as long as the client does | such mistaken use are quite limited as long as the client does | |||
not issue it | not issue it | |||
before all necessary reclaims are done. | before all necessary reclaims are done. | |||
</t> | </li> | |||
<t> | <li> | |||
When a server might become the destination for a file system being | When a server might become the destination for a file system being | |||
migrated, inappropriate use of per-fs RECLAIM_COMPLETE is more | migrated, inappropriate use of per-fs RECLAIM_COMPLETE is more | |||
concerning. In the case in which the file system designated is not | concerning. In the case in which the file system designated is not | |||
within a per-fs grace period, the per-fs RECLAIM_COMPLETE SHOULD | within a per-fs grace period, the per-fs RECLAIM_COMPLETE <bcp14>SHOULD</ bcp14> | |||
be ignored, with the | be ignored, with the | |||
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. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="OP_ILLEGAL" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 10044: ILLEGAL - Illegal Operation</name> | |||
$ --> | <section toc="exclude" anchor="OP_ILLEGAL_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <name>ARGUMENTS</name> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <sourcecode type="xdr"><![CDATA[ | |||
<section anchor="OP_ILLEGAL" title="Operation 10044: ILLEGAL - Illegal Operation | void;]]></sourcecode> | |||
" > | </section> | |||
<section toc="exclude" anchor="OP_ILLEGAL_RESULTS" numbered="true"> | ||||
<section toc="exclude" anchor="OP_ILLEGAL_ARGUMENTS" title="ARGUMENTS"> | <name>RESULTS</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
void; | ||||
</artwork> | ||||
</figure> | ||||
</section> | ||||
<section toc="exclude" anchor="OP_ILLEGAL_RESULTS" title="RESULTS"> | ||||
<figure> | ||||
<artwork> | ||||
struct ILLEGAL4res { | struct ILLEGAL4res { | |||
nfsstat4 status; | nfsstat4 status; | |||
}; | };]]></sourcecode> | |||
</section> | ||||
</artwork> | <section toc="exclude" anchor="OP_ILLEGAL_DESCRIPTION" numbered="true"> | |||
</figure> | <name>DESCRIPTION</name> | |||
</section> | <t> | |||
<section toc="exclude" anchor="OP_ILLEGAL_DESCRIPTION" title="DESCRIPTION"> | ||||
<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 | |||
details. | details. | |||
</t> | </t> | |||
<t> | <t> | |||
The status field of ILLEGAL4res MUST be set to NFS4ERR_OP_ILLEGAL. | The status field of ILLEGAL4res <bcp14>MUST</bcp14> be set to NFS4ERR_OP_I | |||
</t> | LLEGAL. | |||
</section> | </t> | |||
<section toc="exclude" anchor="OP_ILLEGAL_IMPLEMENTATION" title="IMPLEMENTATIO | </section> | |||
N"> | <section toc="exclude" anchor="OP_ILLEGAL_IMPLEMENTATION" numbered="true | |||
<t> | "> | |||
<name>IMPLEMENTATION</name> | ||||
<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> | |||
<!-- $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 | <section anchor="nfsv41callbackprocedures" numbered="true" toc="default"> | |||
$ --> | <name>NFSv4.1 Callback Procedures</name> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <t> | |||
<!-- Copyright (C) The Internet Society (2006) --> | ||||
<section anchor="nfsv41callbackprocedures" title="NFSv4.1 Callback Procedures"> | ||||
<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, MUST be implemented. | Both procedures, CB_NULL and CB_COMPOUND, <bcp14>MUST</bcp14> be implemented. | |||
</t> | </t> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="PROC_CB_NULL" numbered="true" toc="default"> | |||
$ --> | <name>Procedure 0: CB_NULL - No Operation</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="PROC_CB_NULL_ARGUMENTS" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENTS</name> | |||
<section anchor="PROC_CB_NULL" title="Procedure 0: CB_NULL - No Operation" > | <sourcecode type="xdr"><![CDATA[ | |||
void;]]></sourcecode> | ||||
<section toc="exclude" anchor="PROC_CB_NULL_ARGUMENTS" title="ARGUMENTS"> | </section> | |||
<figure> | <section toc="exclude" anchor="PROC_CB_NULL_RESULTS" numbered="true"> | |||
<artwork> | <name>RESULTS</name> | |||
void; | <sourcecode type="xdr"><![CDATA[ | |||
</artwork> | void;]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="PROC_CB_NULL_DESCRIPTION" numbered="true" | |||
> | ||||
<section toc="exclude" anchor="PROC_CB_NULL_RESULTS" title="RESULTS"> | <name>DESCRIPTION</name> | |||
<figure> | <t> | |||
<artwork> | ||||
void; | ||||
</artwork> | ||||
</figure> | ||||
</section> | ||||
<section toc="exclude" anchor="PROC_CB_NULL_DESCRIPTION" title="DESCRIPTION"> | ||||
<t> | ||||
CB_NULL is the standard ONC RPC NULL procedure, with the standard void arg ument and void response. Even though | CB_NULL is the standard ONC RPC NULL procedure, with the standard void arg ument 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"> | |||
<name>ERRORS</name> | ||||
<section toc="exclude" anchor="PROC_CB_NULL_ERRORS" title="ERRORS"> | <t> | |||
<t> | ||||
None. | None. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="PROC_CB_COMPOUND" numbered="true" toc="default"> | |||
$ --> | <name>Procedure 1: CB_COMPOUND - Compound Operations</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="PROC_CB_COMPOUND_ARGUMENTS" numbered="tru | |||
<!-- Copyright (C) The Internet Society (2006) --> | e"> | |||
<section anchor="PROC_CB_COMPOUND" title="Procedure 1: CB_COMPOUND - Compound Op | <name>ARGUMENTS</name> | |||
erations" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="PROC_CB_COMPOUND_ARGUMENTS" title="ARGUMENTS"> | ||||
<figure> | ||||
<artwork> | ||||
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, | |||
OP_CB_SEQUENCE = 11, | OP_CB_SEQUENCE = 11, | |||
OP_CB_WANTS_CANCELLED = 12, | OP_CB_WANTS_CANCELLED = 12, | |||
OP_CB_NOTIFY_LOCK = 13, | OP_CB_NOTIFY_LOCK = 13, | |||
OP_CB_NOTIFY_DEVICEID = 14, | OP_CB_NOTIFY_DEVICEID = 14, | |||
OP_CB_ILLEGAL = 10044 | OP_CB_ILLEGAL = 10044 | |||
}; | }; | |||
</artwork> | ||||
</figure> | ||||
<figure> | ||||
<artwork> | ||||
union nfs_cb_argop4 switch (unsigned argop) { | union nfs_cb_argop4 switch (unsigned argop) { | |||
case OP_CB_GETATTR: | case OP_CB_GETATTR: | |||
CB_GETATTR4args opcbgetattr; | CB_GETATTR4args opcbgetattr; | |||
case OP_CB_RECALL: | case OP_CB_RECALL: | |||
CB_RECALL4args opcbrecall; | CB_RECALL4args opcbrecall; | |||
case OP_CB_LAYOUTRECALL: | case OP_CB_LAYOUTRECALL: | |||
CB_LAYOUTRECALL4args opcblayoutrecall; | CB_LAYOUTRECALL4args opcblayoutrecall; | |||
case OP_CB_NOTIFY: | case OP_CB_NOTIFY: | |||
CB_NOTIFY4args opcbnotify; | CB_NOTIFY4args opcbnotify; | |||
case OP_CB_PUSH_DELEG: | case OP_CB_PUSH_DELEG: | |||
skipping to change at line 40299 ¶ | skipping to change at line 40177 ¶ | |||
case OP_CB_SEQUENCE: | case OP_CB_SEQUENCE: | |||
CB_SEQUENCE4args opcbsequence; | CB_SEQUENCE4args opcbsequence; | |||
case OP_CB_WANTS_CANCELLED: | case OP_CB_WANTS_CANCELLED: | |||
CB_WANTS_CANCELLED4args opcbwants_cancelled; | CB_WANTS_CANCELLED4args opcbwants_cancelled; | |||
case OP_CB_NOTIFY_LOCK: | case OP_CB_NOTIFY_LOCK: | |||
CB_NOTIFY_LOCK4args opcbnotify_lock; | CB_NOTIFY_LOCK4args opcbnotify_lock; | |||
case OP_CB_NOTIFY_DEVICEID: | case OP_CB_NOTIFY_DEVICEID: | |||
CB_NOTIFY_DEVICEID4args opcbnotify_deviceid; | CB_NOTIFY_DEVICEID4args opcbnotify_deviceid; | |||
case OP_CB_ILLEGAL: void; | case OP_CB_ILLEGAL: void; | |||
}; | }; | |||
</artwork> | ||||
</figure> | ||||
<figure> | ||||
<artwork> | ||||
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<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
<section toc="exclude" anchor="PROC_CB_COMPOUND_RESULTS" numbered="true" | ||||
</section> | > | |||
<name>RESULTS</name> | ||||
<section toc="exclude" anchor="PROC_CB_COMPOUND_RESULTS" title="RESULTS"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
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 40359 ¶ | skipping to change at line 40231 ¶ | |||
CB_NOTIFY_LOCK4res | CB_NOTIFY_LOCK4res | |||
opcbnotify_lock; | opcbnotify_lock; | |||
case OP_CB_NOTIFY_DEVICEID: | case OP_CB_NOTIFY_DEVICEID: | |||
CB_NOTIFY_DEVICEID4res | CB_NOTIFY_DEVICEID4res | |||
opcbnotify_deviceid; | opcbnotify_deviceid; | |||
/* Not new operation */ | /* Not new operation */ | |||
case OP_CB_ILLEGAL: CB_ILLEGAL4res opcbillegal; | case OP_CB_ILLEGAL: CB_ILLEGAL4res opcbillegal; | |||
}; | }; | |||
</artwork> | ||||
</figure> | ||||
<figure> | ||||
<artwork> | ||||
struct CB_COMPOUND4res { | struct CB_COMPOUND4res { | |||
nfsstat4 status; | nfsstat4 status; | |||
utf8str_cs tag; | utf8str_cs tag; | |||
nfs_cb_resop4 resarray<>; | nfs_cb_resop4 resarray<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_CB_COMPOUND_DESCRIPTION" numbered="tru | |||
e"> | ||||
<section toc="exclude" anchor="OP_CB_COMPOUND_DESCRIPTION" title="DESCRIPTION" | <name>DESCRIPTION</name> | |||
> | <t> | |||
<t> | ||||
The CB_COMPOUND procedure is used to combine one or more of the | The CB_COMPOUND procedure is used to combine one or more of the | |||
callback procedures into a single RPC request. The main callback RPC | callback procedures into a single RPC request. The main callback RPC | |||
program has two main procedures: CB_NULL and CB_COMPOUND. All other | program has two main procedures: CB_NULL and CB_COMPOUND. All other | |||
operations use the CB_COMPOUND procedure as a wrapper. | operations use the CB_COMPOUND procedure as a wrapper. | |||
</t> | </t> | |||
<t> | <t> | |||
During the processing of the CB_COMPOUND procedure, the client may find | During the processing of the CB_COMPOUND procedure, the client may find | |||
that it does not have the available resources to execute any or all of | that it does not have the available resources to execute any or all of | |||
the operations within the CB_COMPOUND sequence. | the operations within the CB_COMPOUND sequence. | |||
Refer to <xref target="COMPOUND_Sizing_Issues" /> for details. | Refer to <xref target="COMPOUND_Sizing_Issues" format="default"/> for deta | |||
</t> | ils. | |||
<t> | </t> | |||
The minorversion field of the arguments MUST be the same as the | <t> | |||
The minorversion field of the arguments <bcp14>MUST</bcp14> be the same as | ||||
the | ||||
minorversion of the COMPOUND procedure used to create the client ID | minorversion of the COMPOUND procedure used to create the client ID | |||
and session. For NFSv4.1, minorversion MUST be set to 1. | and session. For NFSv4.1, minorversion <bcp14>MUST</bcp14> be set to 1. | |||
</t> | </t> | |||
<t> | <t> | |||
Contained within the CB_COMPOUND results is a "status" field. This | Contained within the CB_COMPOUND results is a "status" field. This | |||
status MUST be equal to the status of the last operation that was | status <bcp14>MUST</bcp14> be equal to the status of the last operation th at was | |||
executed within the CB_COMPOUND procedure. Therefore, if an operation | executed within the CB_COMPOUND procedure. Therefore, if an operation | |||
incurred an error, then the "status" value will be the same error value | incurred an error, then the "status" value will be the same error value | |||
as is being returned for the operation that failed. | as is being returned for the operation that failed. | |||
</t> | </t> | |||
<t> | <t> | |||
The "tag" field is handled the same way as that of the COMPOUND | The "tag" field is handled the same way as that of the COMPOUND | |||
procedure (see <xref target="OP_COMPOUND_DESCRIPTION" />). | procedure (see <xref target="OP_COMPOUND_DESCRIPTION" format="default"/>). | |||
</t> | </t> | |||
<t> | <t> | |||
Illegal operation codes are handled in the same way as they are | Illegal operation codes are handled in the same way as they are | |||
handled for the COMPOUND procedure. | handled for the COMPOUND procedure. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="PROC_CB_COMPOUND_IMPLEMENTATION" title="IMPLEME | <section toc="exclude" anchor="PROC_CB_COMPOUND_IMPLEMENTATION" numbered | |||
NTATION"> | ="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
The CB_COMPOUND procedure is used to combine individual operations | The CB_COMPOUND procedure is used to combine individual operations | |||
into a single RPC request. The client interprets each of the | into a single RPC request. The client interprets each of the | |||
operations in turn. If an operation is executed by the client and | operations in turn. If an operation is executed by the client and | |||
the status of that operation is NFS4_OK, then the next operation in | the status of that operation is NFS4_OK, then the next operation in | |||
the CB_COMPOUND procedure is executed. The client continues this | the CB_COMPOUND procedure is executed. The client continues this | |||
process until there are no more operations to be executed or one of | process until there are no more operations to be executed or one of | |||
the operations has a status value other than NFS4_OK. | the operations has a status value other than NFS4_OK. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_CB_COMPOUND_ERRORS" title="ERRORS"> | <section toc="exclude" anchor="OP_CB_COMPOUND_ERRORS" numbered="true"> | |||
<t> | <name>ERRORS</name> | |||
<t> | ||||
CB_COMPOUND will of course return every error that each operation on | CB_COMPOUND will of course return every error that each operation on | |||
the backchannel can return (see <xref target="cb_op_error_returns"/>). | the backchannel can return (see <xref target="cb_op_error_returns" format=" default"/>). | |||
However, if CB_COMPOUND returns zero operations, obviously the error | However, if CB_COMPOUND returns zero operations, obviously the error | |||
returned by COMPOUND has nothing to do with an error returned by | returned by COMPOUND has nothing to do with an error returned by | |||
an operation. The list of errors CB_COMPOUND will return if it processes | an operation. The list of errors CB_COMPOUND will return if it processes | |||
zero operations includes: | zero operations includes: | |||
</t> | </t> | |||
<texttable anchor="CB_compounderrs"> | <table anchor="CB_compounderrs" align="center"> | |||
<preamble>CB_COMPOUND error returns</preamble> | <name>CB_COMPOUND Error Returns</name> | |||
<ttcol align='left'>Error</ttcol> | <thead> | |||
<ttcol align='left'>Notes</ttcol> | <tr> | |||
<th align="left">Error</th> | ||||
<c>NFS4ERR_BADCHAR</c> <c>The tag argument has a character the replier | <th align="left">Notes</th> | |||
does not support. </c> | </tr> | |||
</thead> | ||||
<c>NFS4ERR_BADXDR</c> <c> </c> | <tbody> | |||
<tr> | ||||
<c>NFS4ERR_DELAY</c> <c> </c> | <td align="left">NFS4ERR_BADCHAR</td> | |||
<td align="left">The tag argument has a character the replier | ||||
<c>NFS4ERR_INVAL</c> <c>The tag argument is not in UTF-8 encoding.</c> | does not support. </td> | |||
</tr> | ||||
<c>NFS4ERR_MINOR_VERS_MISMATCH</c> <c> </c> | <tr> | |||
<td align="left">NFS4ERR_BADXDR</td> | ||||
<c>NFS4ERR_SERVERFAULT</c> <c> </c> | <td align="left"> </td> | |||
</tr> | ||||
<c>NFS4ERR_TOO_MANY_OPS</c> <c> </c> | <tr> | |||
<td align="left">NFS4ERR_DELAY</td> | ||||
<c>NFS4ERR_REP_TOO_BIG</c> <c> </c> | <td align="left"> </td> | |||
</tr> | ||||
<c>NFS4ERR_REP_TOO_BIG_TO_CACHE</c> <c> </c> | <tr> | |||
<td align="left">NFS4ERR_INVAL</td> | ||||
<c>NFS4ERR_REQ_TOO_BIG</c> <c> </c> | <td align="left">The tag argument is not in UTF-8 encoding.</td> | |||
</tr> | ||||
</texttable> | <tr> | |||
<td align="left">NFS4ERR_MINOR_VERS_MISMATCH</td> | ||||
</section> | <td align="left"> </td> | |||
</section> | </tr> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <tr> | |||
$ --> | <td align="left">NFS4ERR_SERVERFAULT</td> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <td align="left"> </td> | |||
<!-- Copyright (C) The Internet Society (2006) --> | </tr> | |||
<tr> | ||||
<td align="left">NFS4ERR_TOO_MANY_OPS</td> | ||||
<td align="left"> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_REP_TOO_BIG</td> | ||||
<td align="left"> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_REP_TOO_BIG_TO_CACHE</td> | ||||
<td align="left"> </td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">NFS4ERR_REQ_TOO_BIG</td> | ||||
<td align="left"> </td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
</section> | ||||
</section> | ||||
</section> | </section> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="nfsv41cboperations" numbered="true" toc="default"> | |||
$ --> | <name>NFSv4.1 Callback Operations</name> | |||
<!-- Copyright (C) The IETF Trust (2007) --> | <section anchor="OP_CB_GETATTR" numbered="true" toc="default"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>Operation 3: CB_GETATTR - Get Attributes</name> | |||
<section anchor="nfsv41cboperations" title="NFSv4.1 Callback Operations"> | <section toc="exclude" anchor="OP_CB_GETATTR_ARGUMENT" numbered="true"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>ARGUMENT</name> | |||
$ --> | <sourcecode type="xdr"><![CDATA[ | |||
<!-- Copyright (C) The IETF Trust (2007) --> | ||||
<!-- Copyright (C) The Internet Society (2006) --> | ||||
<section anchor="OP_CB_GETATTR" title="Operation 3: CB_GETATTR - Get Attributes" | ||||
> | ||||
<section toc="exclude" anchor="OP_CB_GETATTR_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
struct CB_GETATTR4args { | struct CB_GETATTR4args { | |||
nfs_fh4 fh; | nfs_fh4 fh; | |||
bitmap4 attr_request; | bitmap4 attr_request; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_CB_GETATTR_RESULT" numbered="true"> | |||
<section toc="exclude" anchor="OP_CB_GETATTR_RESULT" title="RESULT"> | <name>RESULT</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
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; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_CB_GETATTR_DESCRIPTION" numbered="true | |||
<section toc="exclude" anchor="OP_CB_GETATTR_DESCRIPTION" title="DESCRIPTION"> | "> | |||
<t> | <name>DESCRIPTION</name> | |||
<t> | ||||
The CB_GETATTR operation is used by the server to obtain the | The CB_GETATTR operation is used by the server to obtain the | |||
current modified state of a file that has been OPEN_DELEGATE_WRITE delegate d. | current modified state of a file that has been OPEN_DELEGATE_WRITE delegate d. | |||
The size and change attributes are the only ones guaranteed to be | The size and change attributes are the only ones guaranteed to be | |||
serviced by the client. See <xref | serviced by the client. See <xref target="handling_cb_getattr" format="def | |||
target="handling_cb_getattr"/> for a full description | ault"/> for a full description | |||
of how the client and server are to interact with | of how the client and server are to interact with | |||
the use of CB_GETATTR. | the use of CB_GETATTR. | |||
</t> | </t> | |||
<t> | <t> | |||
If the filehandle specified is not one for which the client holds an | If the filehandle specified is not one for which the client holds an | |||
OPEN_DELEGATE_WRITE delegation, an NFS4ERR_BADHANDLE error is returned. | OPEN_DELEGATE_WRITE delegation, an NFS4ERR_BADHANDLE error is returned. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_CB_GETATTR_IMPLEMENTATION" title="IMPLEMENTA | <section toc="exclude" anchor="OP_CB_GETATTR_IMPLEMENTATION" numbered="t | |||
TION"> | rue"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_CB_RECALL" numbered="true" toc="default"> | |||
$ --> | <name>Operation 4: CB_RECALL - Recall a Delegation</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_CB_RECALL_ARGUMENT" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENT</name> | |||
<section anchor="OP_CB_RECALL" title="Operation 4: CB_RECALL - Recall a Delegati | <sourcecode type="xdr"><![CDATA[ | |||
on" > | ||||
<section toc="exclude" anchor="OP_CB_RECALL_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
struct CB_RECALL4args { | struct CB_RECALL4args { | |||
stateid4 stateid; | stateid4 stateid; | |||
bool truncate; | bool truncate; | |||
nfs_fh4 fh; | nfs_fh4 fh; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_CB_RECALL_RESULT" numbered="true"> | |||
<section toc="exclude" anchor="OP_CB_RECALL_RESULT" title="RESULT"> | <name>RESULT</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct CB_RECALL4res { | struct CB_RECALL4res { | |||
nfsstat4 status; | nfsstat4 status; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_CB_RECALL_DESCRIPTION" numbered="true" | |||
<section toc="exclude" anchor="OP_CB_RECALL_DESCRIPTION" title="DESCRIPTION"> | > | |||
<t> | <name>DESCRIPTION</name> | |||
<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 | |||
a delegation and returning it to the server. | a delegation and returning it to the server. | |||
</t> | </t> | |||
<t> | <t> | |||
The truncate flag is used to optimize recall for a file object that | The truncate flag is used to optimize recall for a file object that | |||
is a regular file and is | is a regular file and is | |||
about to be truncated to zero. When it is TRUE, the client is freed | about to be truncated to zero. When it is TRUE, the client is freed | |||
of the obligation to propagate modified data for the file to the | of the obligation to propagate modified data for the file to the | |||
server, since this data is irrelevant. | server, since this data is irrelevant. | |||
</t> | </t> | |||
<t> | <t> | |||
If the handle specified is not one for which the client holds a | If the handle specified is not one for which the client holds a | |||
delegation, an NFS4ERR_BADHANDLE error is returned. | delegation, an NFS4ERR_BADHANDLE error is returned. | |||
</t> | </t> | |||
<t> | <t> | |||
If the stateid specified is not one corresponding to an OPEN | If the stateid specified is not one corresponding to an OPEN | |||
delegation for the file specified by the filehandle, an | delegation for the file specified by the filehandle, an | |||
NFS4ERR_BAD_STATEID is returned. | NFS4ERR_BAD_STATEID is returned. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_CB_RECALL_IMPLEMENTATION" title="IMPLEMENTAT | <section toc="exclude" anchor="OP_CB_RECALL_IMPLEMENTATION" numbered="tr | |||
ION"> | ue"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
The client SHOULD reply to the callback immediately. | <t> | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_CB_LAYOUTRECALL" numbered="true" toc="default"> | |||
$ --> | <name>Operation 5: CB_LAYOUTRECALL - Recall Layout from Client</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_CB_LAYOUTRECALL_ARGUMENT" numbered="tr | |||
<!-- Copyright (C) The Internet Society (2006) --> | ue"> | |||
<section anchor="OP_CB_LAYOUTRECALL" | <name>ARGUMENT</name> | |||
title="Operation 5: CB_LAYOUTRECALL - Recall Layout from Client" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_CB_LAYOUTRECALL_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
/* | /* | |||
* 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 40623 ¶ | skipping to change at line 40501 ¶ | |||
case LAYOUTRECALL4_ALL: | case LAYOUTRECALL4_ALL: | |||
void; | void; | |||
}; | }; | |||
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; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_CB_LAYOUTRECALL_RESULT" numbered="true | |||
<section toc="exclude" anchor="OP_CB_LAYOUTRECALL_RESULT" title="RESULT"> | "> | |||
<figure> | <name>RESULT</name> | |||
<artwork> | <sourcecode type="xdr"><![CDATA[ | |||
struct CB_LAYOUTRECALL4res { | struct CB_LAYOUTRECALL4res { | |||
nfsstat4 clorr_status; | nfsstat4 clorr_status; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_CB_LAYOUTRECALL_DESCRIPTION" numbered= | |||
<section toc="exclude" anchor="OP_CB_LAYOUTRECALL_DESCRIPTION" title="DESCRIPT | "true"> | |||
ION"> | <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 | |||
layouts from the client; as a result, the client will begin the | layouts from the client; as a result, the client will begin the | |||
process of returning layouts via LAYOUTRETURN. The | process of returning layouts via LAYOUTRETURN. The | |||
CB_LAYOUTRECALL operation specifies one of three forms of recall | CB_LAYOUTRECALL operation specifies one of three forms of recall | |||
processing with the value of layoutrecall_type4. The recall is | processing with the value of layoutrecall_type4. The recall is | |||
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: | |||
<list style="hanging"> | </t> | |||
<t hangText="LAYOUTRECALL4_FILE"></t> | <dl newline="true" spacing="normal"> | |||
<t> | <dt>LAYOUTRECALL4_FILE</dt> | |||
<dd><t> | ||||
For a layout to match the recall request, the values of the following fi elds | For a layout to match the recall request, the values of the following fi elds | |||
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 an y | of LAYOUTIOMODE4_ANY. The special value LAYOUTIOMODE4_ANY will match an y | |||
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 MUST be returned using the | matching layout is found, it <bcp14>MUST</bcp14> be returned using the | |||
LAYOUTRETURN operation (see <xref target="OP_LAYOUTRETURN" />). | LAYOUTRETURN operation (see <xref target="OP_LAYOUTRETURN" format="defau | |||
lt"/>). | ||||
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> | |||
</t> | <t> | |||
<t> | ||||
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> | |||
</t> | </dd> | |||
<t hangText="LAYOUTRECALL4_FSID and LAYOUTRECALL4_ALL"></t> | <dt>LAYOUTRECALL4_FSID and LAYOUTRECALL4_ALL</dt> | |||
<t> | <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 MUST 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 MUST be returned. In addition, LAYOUTRECALL4_FSID and | layouts <bcp14>MUST</bcp14> be returned. In addition, LAYOUTRECALL4_FSI D 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" /> for considerations with | See <xref target="bulk_layouts" format="default"/> for considerations wi th | |||
"bulk" recall of layouts. | "bulk" recall of layouts. | |||
</t> | </t> | |||
<t> | <t> | |||
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> | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | <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 | |||
LAYOUTRETURN. A TRUE value for clora_changed indicates that the | LAYOUTRETURN. A TRUE value for clora_changed indicates that the | |||
server is changing the layout. Examples of layout changes and | server is changing the layout. Examples of layout changes and | |||
reasons for a TRUE indication are the following: the metadata server is re striping | reasons for a TRUE indication are the following: the metadata server is re striping | |||
the file or a permanent error has occurred on a storage device | the file or a permanent error has occurred on a storage device | |||
and the metadata server would like to provide a new layout for | and the metadata server would like to provide a new layout for | |||
the file. Therefore, a clora_changed value of TRUE indicates | the file. Therefore, a clora_changed value of TRUE indicates | |||
some level of change for the layout and the client SHOULD NOT | some level of change for the layout and the client <bcp14>SHOULD NOT</bcp1 4> | |||
write and commit modified data to the storage devices. In this | write and commit modified data to the storage devices. In this | |||
case, the client writes and commits data through the metadata | case, the client writes and commits data through the metadata | |||
server. | server. | |||
</t> | </t> | |||
<t> | <t> | |||
See <xref target="layout_stateid"/> for a description of how the | See <xref target="layout_stateid" format="default"/> for a description of | |||
how the | ||||
lor_stateid field in the arguments is to be constructed. Note | lor_stateid field in the arguments is to be constructed. Note | |||
that the "seqid" field of lor_stateid MUST NOT be zero. See Sections | that the "seqid" field of lor_stateid <bcp14>MUST NOT</bcp14> be zero. Se | |||
<xref target="stateid" format="counter" />, <xref | e Sections | |||
target="layout_stateid" format="counter" />, and | <xref target="stateid" format="counter"/>, <xref target="layout_stateid" f | |||
<xref target="pnfs_operation_sequencing" format="counter" /> for a further | ormat="counter"/>, and | |||
<xref target="pnfs_operation_sequencing" format="counter"/> for a further | ||||
discussion and requirements. | discussion and requirements. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_CB_LAYOUTRECALL_IMPLEMENTATION" title="IMPLE | <section toc="exclude" anchor="OP_CB_LAYOUTRECALL_IMPLEMENTATION" number | |||
MENTATION"> | ed="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
The client's processing for CB_LAYOUTRECALL is similar to | The client's processing for CB_LAYOUTRECALL is similar to | |||
CB_RECALL (recall of file delegations) in that | CB_RECALL (recall of file delegations) in that | |||
the client responds to | the client responds to | |||
the request before actually returning layouts via the | the request before actually returning layouts via the | |||
LAYOUTRETURN operation. While the client responds to the | LAYOUTRETURN operation. While the client responds to the | |||
CB_LAYOUTRECALL immediately, the operation is not considered | CB_LAYOUTRECALL immediately, the operation is not considered | |||
complete (i.e., considered pending) until all affected layouts are returne d to the server | complete (i.e., considered pending) until all affected layouts are returne d to the server | |||
via the LAYOUTRETURN operation. | via the LAYOUTRETURN operation. | |||
</t> | </t> | |||
<t> | <t> | |||
Before returning the layout to the server via LAYOUTRETURN, the | Before returning the layout to the server via LAYOUTRETURN, the | |||
client should wait for the response from in-process or in-flight | client should wait for the response from in-process or in-flight | |||
READ, WRITE, or COMMIT operations that use the recalled layout. | READ, WRITE, or COMMIT operations that use the recalled layout. | |||
</t> | </t> | |||
<t> | <t> | |||
If the client is holding modified data that is affected by a | If the client is holding modified data that is affected by a | |||
recalled layout, the client has various options for writing the | recalled layout, the client has various options for writing the | |||
data to the server. As always, the client may write the data | data to the server. As always, the client may write the data | |||
through the metadata server. In fact, the client may not have a | through the metadata server. In fact, the client may not have a | |||
choice other than writing to the metadata server when the | choice other than writing to the metadata server when the | |||
clora_changed argument is TRUE and a new layout is unavailable | clora_changed argument is TRUE and a new layout is unavailable | |||
from the server. However, the client may be able to write the | from the server. However, the client may be able to write the | |||
modified data to the storage device if the clora_changed | modified data to the storage device if the clora_changed | |||
argument is FALSE; this needs to be done before returning the | argument is FALSE; this needs to be done before returning the | |||
layout via LAYOUTRETURN. If the client were to obtain a new | layout via LAYOUTRETURN. If the client were to obtain a new | |||
layout covering the modified data's byte-range, then writing to the | layout covering the modified data's byte-range, then writing to the | |||
storage devices is an available alternative. Note that before | storage devices is an available alternative. Note that before | |||
obtaining a new layout, the client must first return the | obtaining a new layout, the client must first return the | |||
original layout. | original layout. | |||
</t> | </t> | |||
<t> | <t> | |||
In the case of modified data being written while the layout is | In the case of modified data being written while the layout is | |||
held, the client must use LAYOUTCOMMIT operations at the | held, the client must use LAYOUTCOMMIT operations at the | |||
appropriate time; as required LAYOUTCOMMIT must be done before | appropriate time; as required LAYOUTCOMMIT must be done before | |||
the LAYOUTRETURN. If a large amount of modified data is | the LAYOUTRETURN. If a large amount of modified data is | |||
outstanding, the client may send LAYOUTRETURNs for portions of | outstanding, the client may send LAYOUTRETURNs for portions of | |||
the recalled layout; this allows the server to monitor the | the recalled layout; this allows the server to monitor the | |||
client's progress and adherence to the original recall request. | client's progress and adherence to the original recall request. | |||
However, the last LAYOUTRETURN in a sequence of returns MUST | However, the last LAYOUTRETURN in a sequence of returns <bcp14>MUST</bcp14 | |||
specify the full range being recalled (see <xref | > | |||
target="recall_robustness" /> for details). | specify the full range being recalled (see <xref target="recall_robustness | |||
</t> | " format="default"/> for details). | |||
<t> | </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 MUST 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 MAY revoke | does not return the affected layouts, the server <bcp14>MAY</bcp14> revoke | |||
the layouts. | the layouts. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | </section> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_CB_NOTIFY" numbered="true" toc="default"> | |||
$ --> | <name>Operation 6: CB_NOTIFY - Notify Client of Directory Changes</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_CB_NOTIFY_ARGUMENT" numbered="true"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENT</name> | |||
<section anchor="OP_CB_NOTIFY" title="Operation 6: CB_NOTIFY - Notify Client of | <sourcecode type="xdr"><![CDATA[ | |||
Directory Changes" > | ||||
<section toc="exclude" anchor="OP_CB_NOTIFY_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
/* | /* | |||
* 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 40821 ¶ | skipping to change at line 40693 ¶ | |||
struct notify_remove4 { | struct notify_remove4 { | |||
notify_entry4 nrm_old_entry; | notify_entry4 nrm_old_entry; | |||
nfs_cookie4 nrm_old_entry_cookie; | nfs_cookie4 nrm_old_entry_cookie; | |||
}; | }; | |||
struct notify_add4 { | struct notify_add4 { | |||
/* | /* | |||
* Information on object | * Information on object | |||
* possibly renamed over. | * possibly renamed over. | |||
*/ | */ | |||
notify_remove4 nad_old_entry<1>; | notify_remove4 nad_old_entry<1>; | |||
notify_entry4 nad_new_entry; | notify_entry4 nad_new_entry; | |||
/* what READDIR would have returned for this entry */ | /* what READDIR would have returned for this entry */ | |||
nfs_cookie4 nad_new_entry_cookie<1>; | nfs_cookie4 nad_new_entry_cookie<1>; | |||
prev_entry4 nad_prev_entry<1>; | prev_entry4 nad_prev_entry<1>; | |||
bool nad_last_entry; | bool nad_last_entry; | |||
}; | }; | |||
struct notify_attr4 { | struct notify_attr4 { | |||
notify_entry4 na_changed_entry; | notify_entry4 na_changed_entry; | |||
}; | }; | |||
struct notify_rename4 { | struct notify_rename4 { | |||
notify_remove4 nrn_old_entry; | notify_remove4 nrn_old_entry; | |||
notify_add4 nrn_new_entry; | notify_add4 nrn_new_entry; | |||
}; | }; | |||
struct notify_verifier4 { | struct notify_verifier4 { | |||
verifier4 nv_old_cookieverf; | verifier4 nv_old_cookieverf; | |||
verifier4 nv_new_cookieverf; | verifier4 nv_new_cookieverf; | |||
}; | }; | |||
/* | /* | |||
* Objects of type notify_<>4 and | * Objects of type notify_<>4 and | |||
* notify_device_<>4 are encoded in this. | * notify_device_<>4 are encoded in this. | |||
*/ | */ | |||
typedef opaque notifylist4<>; | typedef opaque notifylist4<>; | |||
struct notify4 { | struct notify4 { | |||
/* composed from notify_type4 or notify_deviceid_type4 */ | /* composed from notify_type4 or notify_deviceid_type4 */ | |||
bitmap4 notify_mask; | bitmap4 notify_mask; | |||
notifylist4 notify_vals; | notifylist4 notify_vals; | |||
}; | }; | |||
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<>; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_CB_NOTIFY_RESULT" numbered="true"> | |||
<section toc="exclude" anchor="OP_CB_NOTIFY_RESULT" title="RESULT"> | <name>RESULT</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct CB_NOTIFY4res { | struct CB_NOTIFY4res { | |||
nfsstat4 cnr_status; | nfsstat4 cnr_status; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_CB_NOTIFY_DESCRIPTION" numbered="true" | |||
<section toc="exclude" anchor="OP_CB_NOTIFY_DESCRIPTION" title="DESCRIPTION"> | > | |||
<t> | <name>DESCRIPTION</name> | |||
<t> | ||||
The CB_NOTIFY operation is used by the server to | The CB_NOTIFY operation is used by the server to | |||
send notifications to clients about changes to | send notifications to clients about changes to | |||
delegated directories. | delegated directories. | |||
The registration of notifications for the directories | The registration of notifications for the directories | |||
occurs when the delegation is established using | occurs when the delegation is established using | |||
GET_DIR_DELEGATION. | GET_DIR_DELEGATION. | |||
These notifications are sent over the backchannel. The | These notifications are sent over the backchannel. The | |||
notification is sent once the original request has been | notification is sent once the original request has been | |||
processed on the server. The server will send an array of | processed on the server. The server will send an array of | |||
notifications for changes that might have occurred in the | notifications for changes that might have occurred in the | |||
directory. The notifications are sent as list of pairs of | directory. The notifications are sent as list of pairs of | |||
bitmaps and values. | bitmaps and values. | |||
See <xref target="fattr4" /> | See <xref target="fattr4" format="default"/> | |||
for a description of how NFSv4.1 bitmaps work. | for a description of how NFSv4.1 bitmaps work. | |||
</t> | </t> | |||
<t> | <t> | |||
If the server has more notifications than can fit in | If the server has more notifications than can fit in | |||
the CB_COMPOUND request, it SHOULD send a sequence of | the CB_COMPOUND request, it <bcp14>SHOULD</bcp14> send a sequence of | |||
serial CB_COMPOUND requests so that the client's view | serial CB_COMPOUND requests so that the client's view | |||
of the directory does not become confused. For example, if the | of the directory does not become confused. For example, if the | |||
server indicates that a file named "foo" is added and that the | server indicates that a file named "foo" is added and that the | |||
file "foo" is removed, the order in which the client receives | file "foo" is removed, the order in which the client receives | |||
these notifications needs to be the same as the | these notifications needs to be the same as the | |||
order in which the corresponding operations occurred on the server. | order in which the corresponding operations occurred on the server. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
If the client holding the delegation makes any | If the client holding the delegation makes any | |||
changes in the directory that cause files or sub-directories to | changes in the directory that cause files or sub-directories to | |||
be added or removed, the server will | be added or removed, the server will | |||
notify that client of the resulting change(s). If the | notify that client of the resulting change(s). If the | |||
client holding the delegation is making attribute | client holding the delegation is making attribute | |||
or cookie verifier changes only, the server does | or cookie verifier changes only, the server does | |||
not need to send notifications to that client. | not need to send notifications to that client. | |||
The server will send the following information for | The server will send the following information for | |||
each operation: | each operation: | |||
<list style="hanging"> | </t> | |||
<t hangText="NOTIFY4_ADD_ENTRY"><vspace /> | <dl newline="true" spacing="normal"> | |||
<dt>NOTIFY4_ADD_ENTRY</dt> | ||||
<dd> | ||||
The server will send | The server will send | |||
information about the new directory entry being created along with the | information about the new directory entry being created along with the | |||
cookie for that entry. The entry information (data type | cookie for that entry. The entry information (data type | |||
notify_add4) includes the component name of the entry and | notify_add4) includes the component name of the entry and | |||
attributes. The server will send this type of entry when a | attributes. The server will send this type of entry when a | |||
file is actually being created, when an entry is being added | file is actually being created, when an entry is being added | |||
to a directory as a result of a rename across directories | to a directory as a result of a rename across directories | |||
(see below), and when a hard link is being created to an | (see below), and when a hard link is being created to an | |||
existing file. If this entry is added to the end of the | existing file. If this entry is added to the end of the | |||
directory, the server will set the nad_last_entry flag to | directory, the server will set the nad_last_entry flag to | |||
skipping to change at line 40941 ¶ | skipping to change at line 40813 ¶ | |||
of up to one element. If the array is of zero length, there | of up to one element. If the array is of zero length, there | |||
is no previous entry), along with its cookie. This is to | is no previous entry), along with its cookie. This is to | |||
help clients find the right location in their file name caches and | help clients find the right location in their file name caches and | |||
directory caches where this entry should be cached. If the | directory caches where this entry should be cached. If the | |||
new entry's cookie is available, it will be in | new entry's cookie is available, it will be in | |||
the nad_new_entry_cookie (another variable-length array of up to | the nad_new_entry_cookie (another variable-length array of up to | |||
one element) field. If the addition of the entry causes another | one element) field. If the addition of the entry causes another | |||
entry to be deleted (which can only happen in the rename | entry to be deleted (which can only happen in the rename | |||
case) atomically with the addition, then information on | case) atomically with the addition, then information on | |||
this entry is reported in nad_old_entry. | this entry is reported in nad_old_entry. | |||
</t> | </dd> | |||
<t hangText="NOTIFY4_REMOVE_ENTRY"><vspace /> | <dt>NOTIFY4_REMOVE_ENTRY</dt> | |||
<dd> | ||||
The server will send information about the directory entry | The server will send information about the directory entry | |||
being deleted. The server will also send the cookie value | being deleted. The server will also send the cookie value | |||
for the deleted entry so that clients can get to the cached | for the deleted entry so that clients can get to the cached | |||
information for this entry. | information for this entry. | |||
</t> | </dd> | |||
<t hangText="NOTIFY4_RENAME_ENTRY"><vspace /> | <dt>NOTIFY4_RENAME_ENTRY</dt> | |||
<dd> | ||||
The server will send information about both | The server will send information about both | |||
the old entry and the new entry. This includes the name and | the old entry and the new entry. This includes the name and | |||
attributes for each entry. In addition, if the rename | attributes for each entry. In addition, if the rename | |||
causes the deletion of an entry (i.e., the case of a file | causes the deletion of an entry (i.e., the case of a file | |||
renamed over), then this is reported in | renamed over), then this is reported in | |||
nrn_new_new_entry.nad_old_entry. | nrn_new_new_entry.nad_old_entry. | |||
This notification is only sent if | This notification is only sent if | |||
both entries are in the same directory. If the rename is | both entries are in the same directory. If the rename is | |||
across directories, the server will send a remove | across directories, the server will send a remove | |||
notification to one directory and an add notification to the | notification to one directory and an add notification to the | |||
other directory, assuming both have a directory delegation. | other directory, assuming both have a directory delegation. | |||
</t> | </dd> | |||
<t | <dt>NOTIFY4_CHANGE_CHILD_ATTRS/NOTIFY4_CHANGE_DIR_ATTRS</dt> | |||
hangText="NOTIFY4_CHANGE_CHILD_ATTRS/NOTIFY4_CHANGE_DIR_ATTRS"><vspace | <dd> | |||
/> | ||||
The client will use the attribute | The client will use the attribute | |||
mask to inform the server of attributes for which it wants to | mask to inform the server of attributes for which it wants to | |||
receive notifications. This change notification can be | receive notifications. This change notification can be | |||
requested for changes to the attributes of the directory | requested for changes to the attributes of the directory | |||
as well as changes to any file's attributes in the directory by | as well as changes to any file's attributes in the directory by | |||
using two separate attribute masks. The client cannot ask | using two separate attribute masks. The client cannot ask | |||
for change attribute notification for a specific file. One attribute | for change attribute notification for a specific file. One attribute | |||
mask covers all the files in the directory. Upon any | mask covers all the files in the directory. Upon any | |||
attribute change, the server will send back the values of | attribute change, the server will send back the values of | |||
changed attributes. Notifications might not make sense for | changed attributes. Notifications might not make sense for | |||
some file system-wide attributes, and it is up to the server to | some file system-wide attributes, and it is up to the server to | |||
decide which subset it wants to support. The client can | decide which subset it wants to support. The client can | |||
negotiate the frequency of attribute notifications by letting | negotiate the frequency of attribute notifications by letting | |||
the server know how often it wants to be notified of an | the server know how often it wants to be notified of an | |||
attribute change. The server will return supported | attribute change. The server will return supported | |||
notification frequencies or an indication that no | notification frequencies or an indication that no | |||
notification is permitted for directory or child attributes | notification is permitted for directory or child attributes | |||
by setting the dir_notif_delay and | by setting the dir_notif_delay and | |||
dir_entry_notif_delay attributes, respectively. | dir_entry_notif_delay attributes, respectively. | |||
</t> | </dd> | |||
<t hangText="NOTIFY4_CHANGE_COOKIE_VERIFIER"><vspace /> | <dt>NOTIFY4_CHANGE_COOKIE_VERIFIER</dt> | |||
<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. | |||
</t> | </dd> | |||
</list> | </dl> | |||
</t> | </section> | |||
</section> | </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="OP_CB_PUSH_DELEG" | ||||
title="Operation 7: CB_PUSH_DELEG - Offer Previously Requested Delegati | ||||
on to Client" > | ||||
<section toc="exclude" anchor="OP_CB_PUSH_DELEG_ARGUMENT" title="ARGUMENT"> | <section anchor="OP_CB_PUSH_DELEG" numbered="true" toc="default"> | |||
<figure> | <name>Operation 7: CB_PUSH_DELEG - Offer Previously Requested Delegation | |||
<artwork> | to Client</name> | |||
<section toc="exclude" anchor="OP_CB_PUSH_DELEG_ARGUMENT" numbered="true | ||||
"> | ||||
<name>ARGUMENT</name> | ||||
<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; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_CB_PUSH_DELEG_RESULT" numbered="true"> | |||
<section toc="exclude" anchor="OP_CB_PUSH_DELEG_RESULT" title="RESULT"> | <name>RESULT</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct CB_PUSH_DELEG4res { | struct CB_PUSH_DELEG4res { | |||
nfsstat4 cpdr_status; | nfsstat4 cpdr_status; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_CB_PUSH_DELEG_DESCRIPTION" numbered="t | |||
<section toc="exclude" anchor="OP_CB_PUSH_DELEG_DESCRIPTION" title="DESCRIPTIO | rue"> | |||
N"> | <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 | |||
client that the delegation it wants (previously indicated | client that the delegation it wants (previously indicated | |||
via a want established from an | via a want established from an | |||
OPEN or WANT_DELEGATION operation) is available and to | OPEN or WANT_DELEGATION operation) is available and to | |||
simultaneously offer the delegation to the client. The client | simultaneously offer the delegation to the client. The client | |||
has the choice of accepting the delegation by returning | has the choice of accepting the delegation by returning | |||
NFS4_OK to the server, delaying the decision to accept the | NFS4_OK to the server, delaying the decision to accept the | |||
offered delegation by returning NFS4ERR_DELAY, | offered delegation by returning NFS4ERR_DELAY, | |||
or permanently rejecting the offer of the | or permanently rejecting the offer of the | |||
delegation by returning NFS4ERR_REJECT_DELEG. | delegation by returning NFS4ERR_REJECT_DELEG. | |||
When a delegation is rejected in this fashion, the want | When a delegation is rejected in this fashion, the want | |||
previously established is permanently deleted and the delegation | previously established is permanently deleted and the delegation | |||
is subject to acquisition by another client. | is subject to acquisition by another client. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_CB_PUSH_DELEG_IMPLEMENTATION" title="IMPLEME | <section toc="exclude" anchor="OP_CB_PUSH_DELEG_IMPLEMENTATION" numbered | |||
NTATION"> | ="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
If the client does return NFS4ERR_DELAY | If the client does return NFS4ERR_DELAY | |||
and there is a conflicting delegation request, the server MAY | and there is a conflicting delegation request, the server <bcp14>MAY</bcp 14> | |||
process it at the expense of the client that returned | process it at the expense of the client that returned | |||
NFS4ERR_DELAY. The client's want will not be cancelled, but | NFS4ERR_DELAY. The client's want will not be cancelled, but | |||
MAY be processed behind other delegation requests or registered | <bcp14>MAY</bcp14> be processed behind other delegation requests or regis tered | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_CB_RECALL_ANY" numbered="true" toc="default"> | |||
$ --> | <name>Operation 8: CB_RECALL_ANY - Keep Any N Recallable Objects</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_CB_RECALL_ANY_ARGUMENT" numbered="true | |||
<!-- Copyright (C) The Internet Society (2006) --> | "> | |||
<section anchor="OP_CB_RECALL_ANY" title="Operation 8: CB_RECALL_ANY - Keep Any | <name>ARGUMENT</name> | |||
N Recallable Objects" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_CB_RECALL_ANY_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
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; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_CB_RECALL_ANY_RESULT" numbered="true"> | |||
<section toc="exclude" anchor="OP_CB_RECALL_ANY_RESULT" title="RESULT"> | <name>RESULT</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct CB_RECALL_ANY4res { | struct CB_RECALL_ANY4res { | |||
nfsstat4 crar_status; | nfsstat4 crar_status; | |||
}; | }; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_CB_RECALL_ANY_DESCRIPTION" numbered="t | |||
<section toc="exclude" anchor="OP_CB_RECALL_ANY_DESCRIPTION" title="DESCRIPTIO | rue"> | |||
N"> | <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 | |||
recallable objects, such as delegations and layouts, without | recallable objects, such as delegations and layouts, without | |||
running out of resources. In such a case, while not optimal, | running out of resources. In such a case, while not optimal, | |||
the server is free to recall individual objects to reduce the load. | the server is free to recall individual objects to reduce the load. | |||
</t> | </t> | |||
<t> | <t> | |||
Because the general purpose of such recallable objects as | Because the general purpose of such recallable objects as | |||
delegations is to eliminate client interaction with the server, | delegations is to eliminate client interaction with the server, | |||
the server cannot interpret lack of recent use as indicating | the server cannot interpret lack of recent use as indicating | |||
that the object is no longer useful. The absence of visible | that the object is no longer useful. The absence of visible | |||
use is consistent with a delegation keeping potential operations | use is consistent with a delegation keeping potential operations | |||
from being sent to the server. In the case of layouts, while it | from being sent to the server. In the case of layouts, while it | |||
is true that the usefulness of a layout | is true that the usefulness of a layout | |||
is indicated by the use of the layout when storage devices receive | is indicated by the use of the layout when storage devices receive | |||
I/O requests, because there is no mandate that a storage | I/O requests, because there is no mandate that a storage | |||
device indicate to the metadata server any past or | device indicate to the metadata server any past or | |||
present use of a layout, the metadata server is not likely to know | present use of a layout, the metadata server is not likely to know | |||
which layouts are good candidates to recall in response to | which layouts are good candidates to recall in response to | |||
low resources. | low resources. | |||
</t> | </t> | |||
<t> | <t> | |||
In order to implement an effective reclaim scheme for such | In order to implement an effective reclaim scheme for such | |||
objects, the server's knowledge of available resources must be | objects, the server's knowledge of available resources must be | |||
used to determine when objects must be recalled with the | used to determine when objects must be recalled with the | |||
clients selecting the actual objects to be returned. | clients selecting the actual objects to be returned. | |||
</t> | </t> | |||
<t> | <t> | |||
Server implementations may differ in their resource allocation | Server implementations may differ in their resource allocation | |||
requirements. For example, one server may share resources among | requirements. For example, one server may share resources among | |||
all classes of recallable objects, whereas another may use | all classes of recallable objects, whereas another may use | |||
separate resource pools for layouts and for delegations, or | separate resource pools for layouts and for delegations, or | |||
further separate resources by types of delegations. | further separate resources by types of delegations. | |||
</t> | </t> | |||
<t> | <t> | |||
When a given resource pool is over-utilized, the server can | When a given resource pool is over-utilized, the server can | |||
send a CB_RECALL_ANY to clients holding recallable objects of | send a CB_RECALL_ANY to clients holding recallable objects of | |||
the types involved, allowing it to keep a certain number of | the types involved, allowing it to keep a certain number of | |||
such objects and return any excess. A mask specifies which | such objects and return any excess. A mask specifies which | |||
types of objects are to be limited. The client chooses, based | types of objects are to be limited. The client chooses, based | |||
on its own knowledge of current usefulness, which of the objects | on its own knowledge of current usefulness, which of the objects | |||
in that class should be returned. | in that class should be returned. | |||
</t> | </t> | |||
<t> | <t> | |||
A number of bits are defined. For some of these, ranges | A number of bits are defined. For some of these, ranges | |||
are defined and it is up to the definition of the storage | are defined and it is up to the definition of the storage | |||
protocol to specify how these are to be used. There are ranges | protocol to specify how these are to be used. There are ranges | |||
reserved for object-based storage | reserved for object-based storage | |||
protocols and for other experimental storage | protocols and for other experimental storage | |||
protocols. An RFC defining such a storage protocol needs to | protocols. An RFC defining such a storage protocol needs to | |||
specify how particular bits within its range are to be used. | specify how particular bits within its range are to be used. | |||
For example, it may specify a mapping between attributes of | For example, it may specify a mapping between attributes of | |||
the layout (read vs. write, size of area) and the bit to be | the layout (read vs. write, size of area) and the bit to be | |||
used, or it may define a field in the layout where the associated | used, or it may define a field in the layout where the associated | |||
bit position is made available by the server to the client. | bit position is made available by the server to the client. | |||
<list style='hanging'> | </t> | |||
<t hangText='RCA4_TYPE_MASK_RDATA_DLG'> | <dl newline="true" spacing="normal"> | |||
</t> | <dt>RCA4_TYPE_MASK_RDATA_DLG</dt> | |||
<t> | <dd> | |||
The client is to return OPEN_DELEGATE_READ delegations on | The client is to return OPEN_DELEGATE_READ delegations on | |||
non-directory file objects. | non-directory file objects. | |||
</t> | </dd> | |||
<dt>RCA4_TYPE_MASK_WDATA_DLG</dt> | ||||
<t hangText='RCA4_TYPE_MASK_WDATA_DLG'> | <dd> | |||
</t> | ||||
<t> | ||||
The client is to return OPEN_DELEGATE_WRITE delegations on | The client is to return OPEN_DELEGATE_WRITE delegations on | |||
regular file objects. | regular file objects. | |||
</t> | </dd> | |||
<dt>RCA4_TYPE_MASK_DIR_DLG</dt> | ||||
<t hangText='RCA4_TYPE_MASK_DIR_DLG'> | <dd> | |||
</t> | ||||
<t> | ||||
The client is to return directory delegations. | The client is to return directory delegations. | |||
</t> | </dd> | |||
<dt>RCA4_TYPE_MASK_FILE_LAYOUT</dt> | ||||
<t hangText='RCA4_TYPE_MASK_FILE_LAYOUT'> | <dd> | |||
</t> | ||||
<t> | ||||
The client is to return layouts of type LAYOUT4_NFSV4_1_FILES. | The client is to return layouts of type LAYOUT4_NFSV4_1_FILES. | |||
</t> | </dd> | |||
<t hangText='RCA4_TYPE_MASK_BLK_LAYOUT'> | <dt>RCA4_TYPE_MASK_BLK_LAYOUT</dt> | |||
</t> | <dd> | |||
<t> | See <xref target="RFC5663" format="default"/> for a description. | |||
See <xref target='RFC5663' /> for a description. | ||||
</t> | ||||
<t hangText='RCA4_TYPE_MASK_OBJ_LAYOUT_MIN to RCA4_TYPE_MASK_OBJ_LAYOUT_MA | </dd> | |||
X'> | <dt>RCA4_TYPE_MASK_OBJ_LAYOUT_MIN to RCA4_TYPE_MASK_OBJ_LAYOUT_MAX</ | |||
</t> | dt> | |||
<t> | <dd> | |||
See <xref target='RFC5664' /> for a description. | See <xref target="RFC5664" format="default"/> for a description. | |||
</t> | </dd> | |||
<t hangText='RCA4_TYPE_MASK_OTHER_LAYOUT_MIN to RCA4_TYPE_MASK_OTHER_LAYOU | <dt>RCA4_TYPE_MASK_OTHER_LAYOUT_MIN to RCA4_TYPE_MASK_OTHER_LAYOUT_M | |||
T_MAX'> | AX</dt> | |||
</t> | <dd> | |||
<t> | ||||
This range is reserved for telling the client to recall | This range is reserved for telling the client to recall | |||
layouts of experimental | layouts of experimental | |||
or site-specific layout types (see <xref | or site-specific layout types (see <xref target="layouttype4" format="de | |||
target='layouttype4'/>). | fault"/>). | |||
</t> | ||||
</list> | ||||
</t> | </dd> | |||
<t> | </dl> | |||
<t> | ||||
When a bit is set in the type mask that corresponds | When a bit is set in the type mask that corresponds | |||
to an undefined type of recallable object, | to an undefined type of recallable object, | |||
NFS4ERR_INVAL MUST be returned. When a bit is set | NFS4ERR_INVAL <bcp14>MUST</bcp14> be returned. When a bit is set | |||
that corresponds to a defined type of object but | that corresponds to a defined type of object but | |||
the client does not support an object of the type, | the client does not support an object of the type, | |||
NFS4ERR_INVAL MUST NOT be returned. Future minor | NFS4ERR_INVAL <bcp14>MUST NOT</bcp14> be returned. Future minor | |||
versions of NFSv4 may expand the set of valid type | versions of NFSv4 may expand the set of valid type | |||
mask bits. | mask bits. | |||
</t> | </t> | |||
<t> | <t> | |||
CB_RECALL_ANY specifies a count of objects that the client may | CB_RECALL_ANY specifies a count of objects that the client may | |||
keep as opposed to a count that the client must return. This | keep as opposed to a count that the client must return. This | |||
is to avoid a potential race between a CB_RECALL_ANY that had a | is to avoid a potential race between a CB_RECALL_ANY that had a | |||
count of objects to free with a set of client-originated | count of objects to free with a set of client-originated | |||
operations to return layouts or delegations. As a result of the | operations to return layouts or delegations. As a result of the | |||
race, the client and server would have differing ideas as to how | race, the client and server would have differing ideas as to how | |||
many objects to return. Hence, the client could mistakenly free | many objects to return. Hence, the client could mistakenly free | |||
too many. | too many. | |||
</t> | </t> | |||
<t> | <t> | |||
If resource demands prompt it, the server may send another | If resource demands prompt it, the server may send another | |||
CB_RECALL_ANY with a lower count, even if it has not yet received | CB_RECALL_ANY with a lower count, even if it has not yet received | |||
an acknowledgment from the client for a previous CB_RECALL_ANY | an acknowledgment from the client for a previous CB_RECALL_ANY | |||
with the same type mask. Although the possibility exists that | with the same type mask. Although the possibility exists that | |||
these will be received by the client in an order different from | these will be received by the client in an order different from | |||
the order in which they were sent, any such permutation of | the order in which they were sent, any such permutation of | |||
the callback stream is harmless. It is the job of the client | the callback stream is harmless. It is the job of the client | |||
to bring down the size of the recallable object set in line | to bring down the size of the recallable object set in line | |||
with each CB_RECALL_ANY received, and until that obligation is | with each CB_RECALL_ANY received, and until that obligation is | |||
met, it cannot be cancelled or modified by any subsequent | met, it cannot be cancelled or modified by any subsequent | |||
CB_RECALL_ANY for the same type mask. Thus, if the server | CB_RECALL_ANY for the same type mask. Thus, if the server | |||
sends two CB_RECALL_ANYs, the effect will be the same as | sends two CB_RECALL_ANYs, the effect will be the same as | |||
if the lower count was sent, whatever the order of recall | if the lower count was sent, whatever the order of recall | |||
receipt. Note that this means that a server may not cancel | receipt. Note that this means that a server may not cancel | |||
the effect of a CB_RECALL_ANY by sending another recall with | the effect of a CB_RECALL_ANY by sending another recall with | |||
a higher count. When a CB_RECALL_ANY is received and the | a higher count. When a CB_RECALL_ANY is received and the | |||
count is already within the limit set or is above a limit | count is already within the limit set or is above a limit | |||
that the client is working to get down to, that callback has no | that the client is working to get down to, that callback has no | |||
effect. | effect. | |||
</t> | </t> | |||
<t> | <t> | |||
Servers are generally free to deny recallable objects | Servers are generally free to deny recallable objects | |||
when insufficient resources are available. Note that the | when insufficient resources are available. Note that the | |||
effect of such a policy is implicitly to give precedence to | effect of such a policy is implicitly to give precedence to | |||
existing objects relative to requested ones, with the result | existing objects relative to requested ones, with the result | |||
that resources might not be optimally used. To prevent this, | that resources might not be optimally used. To prevent this, | |||
servers are well advised to make the point at which they start | servers are well advised to make the point at which they start | |||
sending CB_RECALL_ANY callbacks somewhat below that at which they | sending CB_RECALL_ANY callbacks somewhat below that at which they | |||
cease to give out new delegations and layouts. This allows the | cease to give out new delegations and layouts. This allows the | |||
client to purge its less-used objects whenever appropriate and | client to purge its less-used objects whenever appropriate and | |||
so continue to have its subsequent requests given new resources | so continue to have its subsequent requests given new resources | |||
freed up by object returns. | freed up by object returns. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_CB_RECALL_ANY_IMPLEMENTATION" title="IMPLEME | <section toc="exclude" anchor="OP_CB_RECALL_ANY_IMPLEMENTATION" numbered | |||
NTATION"> | ="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
The client can choose to return any type of object specified | The client can choose to return any type of object specified | |||
by the mask. If a server wishes to limit the use of objects of a | by the mask. If a server wishes to limit the use of objects of a | |||
specific type, it should only specify that type in the mask | specific type, it should only specify that type in the mask | |||
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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_CB_RECALLABLE_OBJ_AVAIL" numbered="true" toc="default"> | |||
$ --> | <name>Operation 9: CB_RECALLABLE_OBJ_AVAIL - Signal Resources for Recall | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | able Objects</name> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <section toc="exclude" anchor="OP_CB_RECALLABLE_OBJ_AVAIL_ARGUMENT" numb | |||
<section anchor="OP_CB_RECALLABLE_OBJ_AVAIL" | ered="true"> | |||
title="Operation 9: CB_RECALLABLE_OBJ_AVAIL - Signal Resources for Reca | <name>ARGUMENT</name> | |||
llable Objects" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_CB_RECALLABLE_OBJ_AVAIL_ARGUMENT" title="ARG | ||||
UMENT"> | ||||
<figure> | ||||
<artwork> | ||||
typedef CB_RECALL_ANY4args CB_RECALLABLE_OBJ_AVAIL4args; | typedef CB_RECALL_ANY4args CB_RECALLABLE_OBJ_AVAIL4args; | |||
]]></sourcecode> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_CB_RECALLABLE_OBJ_AVAIL_RESULT" number | |||
</section> | ed="true"> | |||
<section toc="exclude" anchor="OP_CB_RECALLABLE_OBJ_AVAIL_RESULT" title="RESUL | <name>RESULT</name> | |||
T"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
struct CB_RECALLABLE_OBJ_AVAIL4res { | struct CB_RECALLABLE_OBJ_AVAIL4res { | |||
nfsstat4 croa_status; | nfsstat4 croa_status; | |||
}; | }; | |||
]]></sourcecode> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_CB_RECALLABLE_OBJ_AVAIL_DESCRIPTION" n | |||
</section> | umbered="true"> | |||
<section toc="exclude" anchor="OP_CB_RECALLABLE_OBJ_AVAIL_DESCRIPTION" title=" | <name>DESCRIPTION</name> | |||
DESCRIPTION"> | <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 | |||
objects that might previously have been denied by OPEN, | objects that might previously have been denied by OPEN, | |||
WANT_DELEGATION, GET_DIR_DELEG, or LAYOUTGET. | WANT_DELEGATION, GET_DIR_DELEG, or LAYOUTGET. | |||
</t> | </t> | |||
<t> | <t> | |||
The argument craa_objects_to_keep means the total number of | The argument craa_objects_to_keep means the total number of | |||
recallable objects of the types indicated in the argument | recallable objects of the types indicated in the argument | |||
type_mask that the server believes it can allow the client to | type_mask that the server believes it can allow the client to | |||
have, including the number of such objects the client already | have, including the number of such objects the client already | |||
has. A client that tries to acquire more recallable objects | has. A client that tries to acquire more recallable objects | |||
than the server informs it can have runs the risk of having | than the server informs it can have runs the risk of having | |||
objects recalled. | objects recalled. | |||
</t> | </t> | |||
<t> | <t> | |||
The server is not obligated to reserve the | The server is not obligated to reserve the | |||
difference between the number of the objects | difference between the number of the objects | |||
the client currently has and the value of | the client currently has and the value of | |||
craa_objects_to_keep, nor does delaying the reply | craa_objects_to_keep, nor does delaying the reply | |||
to CB_RECALLABLE_OBJ_AVAIL prevent the server | to CB_RECALLABLE_OBJ_AVAIL prevent the server | |||
from using the resources of the recallable objects | from using the resources of the recallable objects | |||
for another purpose. Indeed, if a client responds | for another purpose. Indeed, if a client responds | |||
slowly to CB_RECALLABLE_OBJ_AVAIL, the server might | slowly to CB_RECALLABLE_OBJ_AVAIL, the server might | |||
interpret the client as having reduced capability | interpret the client as having reduced capability | |||
to manage recallable objects, and so cancel | to manage recallable objects, and so cancel | |||
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> | <section anchor="OP_CB_RECALL_SLOT" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 10: CB_RECALL_SLOT - Change Flow Control Limits</name> | |||
$ --> | <section toc="exclude" anchor="OP_CB_RECALL_SLOT_ARGUMENT" numbered="tru | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | e"> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>ARGUMENT</name> | |||
<section anchor="OP_CB_RECALL_SLOT" title="Operation 10: CB_RECALL_SLOT - Change | <sourcecode type="xdr"><![CDATA[ | |||
Flow Control Limits" > | ||||
<section toc="exclude" anchor="OP_CB_RECALL_SLOT_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
struct CB_RECALL_SLOT4args { | struct CB_RECALL_SLOT4args { | |||
slotid4 rsa_target_highest_slotid; | slotid4 rsa_target_highest_slotid; | |||
}; | }; | |||
]]></sourcecode> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_CB_RECALL_SLOT_RESULT" numbered="true" | |||
</section> | > | |||
<section toc="exclude" anchor="OP_CB_RECALL_SLOT_RESULT" title="RESULT"> | <name>RESULT</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct CB_RECALL_SLOT4res { | struct CB_RECALL_SLOT4res { | |||
nfsstat4 rsr_status; | nfsstat4 rsr_status; | |||
}; | }; | |||
]]></sourcecode> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_CB_RECALL_SLOT_DESCRIPTION" numbered=" | |||
</section> | true"> | |||
<section toc="exclude" anchor="OP_CB_RECALL_SLOT_DESCRIPTION" title="DESCRIPTI | <name>DESCRIPTION</name> | |||
ON"> | <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 | |||
credits (e.g., RDMA credits for connections associated with | credits (e.g., RDMA credits for connections associated with | |||
the operations channel) of the session's fore channel. | the operations channel) of the session's fore channel. | |||
CB_RECALL_SLOT specifies | CB_RECALL_SLOT specifies | |||
rsa_target_highest_slotid, the value of the target highest slot ID the ser ver wants | rsa_target_highest_slotid, the value of the target highest slot ID the ser ver wants | |||
for the session. The client MUST then progress toward reducing | for the session. The client <bcp14>MUST</bcp14> then progress toward reduc ing | |||
the session's highest slot ID to the target value. | the session's highest slot ID to the target value. | |||
</t> | </t> | |||
<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 > | for all outstanding requests with a slot ID > | |||
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 | |||
<!-- 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" title="IMPLEM | <section toc="exclude" anchor="OP_CB_RECALL_SLOT_IMPLEMENTATION" numbere | |||
ENTATION"> | d="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_CB_SEQUENCE" numbered="true" toc="default"> | |||
$ --> | <name>Operation 11: CB_SEQUENCE - Supply Backchannel Sequencing and Cont | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | rol</name> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <section toc="exclude" anchor="OP_CB_SEQUENCE_ARGUMENT" numbered="true"> | |||
<section anchor="OP_CB_SEQUENCE" title="Operation 11: CB_SEQUENCE - Supply Backc | <name>ARGUMENT</name> | |||
hannel Sequencing and Control" > | <sourcecode type="xdr"><![CDATA[ | |||
<section toc="exclude" anchor="OP_CB_SEQUENCE_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
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<>; | |||
}; | }; | |||
struct CB_SEQUENCE4args { | struct CB_SEQUENCE4args { | |||
sessionid4 csa_sessionid; | sessionid4 csa_sessionid; | |||
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> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_CB_SEQUENCE_RESULT" numbered="true"> | |||
</section> | <name>RESULT</name> | |||
<section toc="exclude" anchor="OP_CB_SEQUENCE_RESULT" title="RESULT"> | <sourcecode type="xdr"><![CDATA[ | |||
<figure> | ||||
<artwork> | ||||
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: | |||
CB_SEQUENCE4resok csr_resok4; | CB_SEQUENCE4resok csr_resok4; | |||
default: | default: | |||
void; | void; | |||
}; | }; | |||
]]></sourcecode> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_CB_SEQUENCE_DESCRIPTION" numbered="tru | |||
</section> | e"> | |||
<section toc="exclude" anchor="OP_CB_SEQUENCE_DESCRIPTION" title="DESCRIPTION" | <name>DESCRIPTION</name> | |||
> | <t> | |||
<t> | ||||
The CB_SEQUENCE operation is used to manage operational accounting | The CB_SEQUENCE operation is used to manage operational accounting | |||
for the backchannel of the session on which a request is | for the backchannel of the session on which a request is | |||
sent. The contents include the session ID to which this | sent. The contents include the session ID to which this | |||
request belongs, the slot ID and sequence ID used by the server to | request belongs, the slot ID and sequence ID used by the server to | |||
implement session request control and exactly once | implement session request control and exactly once | |||
semantics, and exchanged slot ID maxima that are used to adjust the | semantics, and exchanged slot ID maxima that are used to adjust the | |||
size of the reply cache. In each CB_COMPOUND request, CB_SEQUENCE | size of the reply cache. In each CB_COMPOUND request, CB_SEQUENCE | |||
MUST appear once and MUST be the first operation. The error | <bcp14>MUST</bcp14> appear once and <bcp14>MUST</bcp14> be the first opera | |||
NFS4ERR_SEQUENCE_POS MUST be returned when CB_SEQUENCE is found in | tion. The error | |||
NFS4ERR_SEQUENCE_POS <bcp14>MUST</bcp14> be returned when CB_SEQUENCE is f | ||||
ound in | ||||
any position in a CB_COMPOUND beyond the first. If any | any position in a CB_COMPOUND beyond the first. If any | |||
other operation is in the first position of CB_COMPOUND, | other operation is in the first position of CB_COMPOUND, | |||
NFS4ERR_OP_NOT_IN_SESSION MUST be returned. | NFS4ERR_OP_NOT_IN_SESSION <bcp14>MUST</bcp14> be returned. | |||
</t> | </t> | |||
<t> | <t> | |||
See <xref target="OP_SEQUENCE_DESCRIPTION"/> for a description of | See <xref target="OP_SEQUENCE_DESCRIPTION" format="default"/> for a descri | |||
ption of | ||||
how slots are processed. | how slots are processed. | |||
</t> | </t> | |||
<t> | <t> | |||
If csa_cachethis is TRUE, then the server is requesting that | If csa_cachethis is TRUE, then the server is requesting that | |||
the client cache the reply in the callback reply cache. The client MUST | the client cache the reply in the callback reply cache. The client <bcp14>M | |||
cache the reply (see <xref target="optional_reply_caching" />). | UST</bcp14> | |||
</t> | cache the reply (see <xref target="optional_reply_caching" format="default" | |||
<t> | />). | |||
</t> | ||||
<t> | ||||
The csa_referring_call_lists array is the list of COMPOUND | The csa_referring_call_lists array is the list of COMPOUND | |||
requests, identified by session ID, slot ID, and sequence ID. These | requests, identified by session ID, slot ID, and sequence ID. These | |||
are requests that the client previously sent to the server. | are requests that the client previously sent to the server. | |||
These previous requests created state that some operation(s) | These previous requests created state that some operation(s) | |||
in the same CB_COMPOUND as the csa_referring_call_lists are | in the same CB_COMPOUND as the csa_referring_call_lists are | |||
identifying. | identifying. | |||
A session ID is included because | A session ID is included because | |||
leased state is tied to a client ID, and a client ID can have | leased state is tied to a client ID, and a client ID can have | |||
multiple sessions. See | multiple sessions. See | |||
<xref target="sessions_callback_races" />. | <xref target="sessions_callback_races" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
The value of the csa_sequenceid argument relative to | The value of the csa_sequenceid argument relative to | |||
the cached sequence ID on the slot falls into one | the cached sequence ID on the slot falls into one | |||
of three cases. | of three cases. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
If the difference between csa_sequenceid and | If the difference between csa_sequenceid and | |||
the client's cached sequence ID at the slot ID | the client's cached sequence ID at the slot ID | |||
is two (2) or more, | is two (2) or more, | |||
or if csa_sequenceid is less | or if csa_sequenceid is less | |||
than the cached sequence ID (accounting | than the cached sequence ID (accounting | |||
for wraparound of the unsigned sequence ID value), | for wraparound of the unsigned sequence ID value), | |||
then the client MUST return NFS4ERR_SEQ_MISORDERED. | then the client <bcp14>MUST</bcp14> return NFS4ERR_SEQ_MISORDERED. | |||
</t> | </li> | |||
<t> | <li> | |||
If csa_sequenceid and the cached sequence ID are the | If csa_sequenceid and the cached sequence ID are the | |||
same, this is a retry, and the client returns the | same, this is a retry, and the client returns the | |||
CB_COMPOUND request's cached reply. | CB_COMPOUND request's cached reply. | |||
</t> | </li> | |||
<t> | <li> | |||
If csa_sequenceid is one greater (accounting for | If csa_sequenceid is one greater (accounting for | |||
wraparound) than the cached sequence ID, then | wraparound) than the cached sequence ID, then | |||
this is a new request, and the slot's sequence | this is a new request, and the slot's sequence | |||
ID is incremented. The operations subsequent to | ID is incremented. The operations subsequent to | |||
CB_SEQUENCE, if any, are processed. If there are no | CB_SEQUENCE, if any, are processed. If there are no | |||
other operations, the only other effects are to | other operations, the only other effects are to | |||
cache the CB_SEQUENCE reply in the slot, maintain the | cache the CB_SEQUENCE reply in the slot, maintain the | |||
session's activity, and when the server receives the | session's activity, and when the server receives the | |||
CB_SEQUENCE reply, renew the lease of state | CB_SEQUENCE reply, renew the lease of state | |||
related to the client ID. | related to the client ID. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
If the server reuses a slot ID and sequence ID for | If the server reuses a slot ID and sequence ID for | |||
a completely different request, the client MAY | a completely different request, the client <bcp14>MAY</bcp14> | |||
treat the request as if it is a retry | treat the request as if it is a retry | |||
of what it has already executed. The client MAY however | of what it has already executed. The client <bcp14>MAY</bcp14> however | |||
detect the server's illegal reuse and return NFS4ERR_SEQ_FALSE_RETRY. | detect the server's illegal reuse and return NFS4ERR_SEQ_FALSE_RETRY. | |||
</t> | </t> | |||
<t> | <t> | |||
If CB_SEQUENCE returns an error, then the state of the slot (sequence ID, | If CB_SEQUENCE returns an error, then the state of the slot (sequence ID, | |||
cached reply) MUST NOT change. | cached reply) <bcp14>MUST NOT</bcp14> change. | |||
See <xref target="optional_reply_caching"/> for the conditions when the | See <xref target="optional_reply_caching" format="default"/> for the condit | |||
ions when the | ||||
error NFS4ERR_RETRY_UNCACHED_REP might be returned. | error NFS4ERR_RETRY_UNCACHED_REP might be returned. | |||
</t> | </t> | |||
<t> | <t> | |||
The client returns two "highest_slotid" values: | The client returns two "highest_slotid" values: | |||
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 SHOULD NOT 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" | <xref target="Slot_Identifiers_and_Server_Reply_Cache" format="default"/> f | |||
/> for an exception). The latter is the highest slot | or 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> | <section anchor="OP_CB_WANTS_CANCELLED" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 12: CB_WANTS_CANCELLED - Cancel Pending Delegation Wants | |||
$ --> | </name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <section toc="exclude" anchor="OP_CB_WANTS_CANCELLED_ARGUMENT" numbered= | |||
<!-- Copyright (C) The Internet Society (2006) --> | "true"> | |||
<section anchor="OP_CB_WANTS_CANCELLED" | <name>ARGUMENT</name> | |||
title="Operation 12: CB_WANTS_CANCELLED - Cancel Pending Delegation Wan | <sourcecode type="xdr"><![CDATA[ | |||
ts " > | ||||
<section toc="exclude" anchor="OP_CB_WANTS_CANCELLED_ARGUMENT" title="ARGUMENT | ||||
"> | ||||
<figure> | ||||
<artwork> | ||||
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> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_CB_WANTS_CANCELLED_RESULT" numbered="t | |||
</section> | rue"> | |||
<section toc="exclude" anchor="OP_CB_WANTS_CANCELLED_RESULT" title="RESULT"> | <name>RESULT</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct CB_WANTS_CANCELLED4res { | struct CB_WANTS_CANCELLED4res { | |||
nfsstat4 cwcr_status; | nfsstat4 cwcr_status; | |||
}; | }; | |||
]]></sourcecode> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_CB_WANTS_CANCELLED_DESCRIPTION" number | |||
</section> | ed="true"> | |||
<section toc="exclude" anchor="OP_CB_WANTS_CANCELLED_DESCRIPTION" title="DESCR | <name>DESCRIPTION</name> | |||
IPTION"> | <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 layo uts | some or all of the wants it registered for recallable delegations and layo uts | |||
have been cancelled. | have been cancelled. | |||
</t> | </t> | |||
<t> | <t> | |||
If cwca_contended_wants_cancelled is TRUE, this indicates that | If cwca_contended_wants_cancelled is TRUE, this indicates that | |||
the server will not be pushing to the client any delegations | the server will not be pushing to the client any delegations | |||
that become available after contention passes. | that become available after contention passes. | |||
</t> | </t> | |||
<t> | <t> | |||
If cwca_resourced_wants_cancelled is TRUE, this indicates that | If cwca_resourced_wants_cancelled is TRUE, this indicates that | |||
the server will not notify the client when there are resources | the server will not notify the client when there are resources | |||
on the server to grant delegations or layouts. | on the server to grant delegations or layouts. | |||
</t> | </t> | |||
<t> | <t> | |||
After receiving a CB_WANTS_CANCELLED operation, the | After receiving a CB_WANTS_CANCELLED operation, the | |||
client is free to attempt to acquire the delegations or | client is free to attempt to acquire the delegations or | |||
layouts it was waiting for, and possibly re-register wants. | layouts it was waiting for, and possibly re-register wants. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section toc="exclude" anchor="OP_CB_WANTS_CANCELLED_IMPLEMENTATION" num | |||
<section toc="exclude" anchor="OP_CB_WANTS_CANCELLED_IMPLEMENTATION" title="IM | bered="true"> | |||
PLEMENTATION"> | <name>IMPLEMENTATION</name> | |||
<t> | <t> | |||
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 availabili ty | make clear to the client whether a promise to signal delegation availabili ty | |||
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> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <section anchor="OP_CB_NOTIFY_LOCK" numbered="true" toc="default"> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <name>Operation 13: CB_NOTIFY_LOCK - Notify Client of Possible Lock Avai | |||
<section anchor="OP_CB_NOTIFY_LOCK" title="Operation 13: CB_NOTIFY_LOCK - Notify | lability</name> | |||
Client of Possible Lock Availability" > | <section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_ARGUMENT" numbered="tru | |||
e"> | ||||
<section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_ARGUMENT" title="ARGUMENT"> | <name>ARGUMENT</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
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> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_RESULT" numbered="true" | |||
</section> | > | |||
<section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_RESULT" title="RESULT"> | <name>RESULT</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct CB_NOTIFY_LOCK4res { | struct CB_NOTIFY_LOCK4res { | |||
nfsstat4 cnlr_status; | nfsstat4 cnlr_status; | |||
}; | }; | |||
]]></sourcecode> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_DESCRIPTION" numbered=" | |||
</section> | true"> | |||
<section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_DESCRIPTION" title="DESCRIPTI | <name>DESCRIPTION</name> | |||
ON"> | <t> | |||
<t> | ||||
The server can use this operation to indicate that a byte-range lock for t he given | The server can use this operation to indicate that a byte-range lock for t he given | |||
file and lock-owner, previously requested by the client via an unsuccessfu l | file and lock-owner, previously requested by the client via an unsuccessfu l | |||
LOCK operation, might be available. | LOCK operation, might be available. | |||
</t> | </t> | |||
<t> | <t> | |||
This callback is meant to be used by servers to help reduce the latency of | This callback is meant to be used by servers to help reduce the latency of | |||
blocking locks in the case where they recognize that a client that has | blocking locks in the case where they recognize that a client that has | |||
been polling for a blocking byte-range lock may now be able to acquire the lock. | been polling for a blocking byte-range lock may now be able to acquire the lock. | |||
If the server supports this callback for a given file, it MUST set the | If the server supports this callback for a given file, it <bcp14>MUST</bcp 14> set the | |||
OPEN4_RESULT_MAY_NOTIFY_LOCK flag when responding to successful opens | OPEN4_RESULT_MAY_NOTIFY_LOCK flag when responding to successful opens | |||
for that file. This does not commit the server to the use of CB_NOTIFY_LO CK, | for that file. This does not commit the server to the use of CB_NOTIFY_LO CK, | |||
but the client may use this as a hint to decide how frequently to poll | but the client may use this as a hint to decide how frequently to poll | |||
for locks derived from that open. | for locks derived from that open. | |||
</t> | </t> | |||
<t> | <t> | |||
If an OPEN operation results in an upgrade, in which the stateid returned | If an OPEN operation results in an upgrade, in which the stateid returned | |||
has an "other" value matching that of a stateid already allocated, with a | has an "other" value matching that of a stateid already allocated, with a | |||
new "seqid" indicating a change in the lock being represented, then the | new "seqid" indicating a change in the lock being represented, then the | |||
value of the OPEN4_RESULT_MAY_NOTIFY_LOCK flag when responding to that new | value of the OPEN4_RESULT_MAY_NOTIFY_LOCK flag when responding to that new | |||
OPEN controls handling from that point going forward. When parallel OPENs | OPEN controls handling from that point going forward. When parallel OPENs | |||
are done on the same file and open-owner, the ordering of the "seqid" fiel ds | are done on the same file and open-owner, the ordering of the "seqid" fiel ds | |||
of the returned stateids (subject to wraparound) are to be used to select | of the returned stateids (subject to wraparound) are to be used to select | |||
the controlling value of the OPEN4_RESULT_MAY_NOTIFY_LOCK flag. | the controlling value of the OPEN4_RESULT_MAY_NOTIFY_LOCK flag. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_IMPLEMENTATION" title="IMPLEM | <section toc="exclude" anchor="OP_CB_NOTIFY_LOCK_IMPLEMENTATION" numbere | |||
ENTATION"> | d="true"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
The server MUST NOT grant the byte-range lock to the client unless and unti | <t> | |||
l it | The server <bcp14>MUST NOT</bcp14> grant the byte-range lock to the client | |||
unless and until it | ||||
receives a LOCK operation from the client. Similarly, the client | receives a LOCK operation from the client. Similarly, the client | |||
receiving this callback cannot assume that it now has the lock or that a | receiving this callback cannot assume that it now has the lock or that a | |||
subsequent LOCK operation for the lock will be successful. | subsequent LOCK operation for the lock will be successful. | |||
</t> | </t> | |||
<t> | <t> | |||
The server is not required to implement this callback, and even if it | The server is not required to implement this callback, and even if it | |||
does, it is not required to use it in any particular case. Therefore, the | does, it is not required to use it in any particular case. Therefore, the | |||
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"/>. | <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 MUST NOT 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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <section anchor="OP_CB_NOTIFY_DEVICEID" numbered="true" toc="default"> | |||
$ --> | <name>Operation 14: CB_NOTIFY_DEVICEID - Notify Client of Device ID Chan | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | ges</name> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <section toc="exclude" anchor="OP_CB_NOTIFY_DEVICEID_ARGUMENT" numbered= | |||
<section anchor="OP_CB_NOTIFY_DEVICEID" title="Operation 14: CB_NOTIFY_DEVICEID | "true"> | |||
- Notify Client of Device ID Changes" > | <name>ARGUMENT</name> | |||
<sourcecode type="xdr"><![CDATA[ | ||||
<section toc="exclude" anchor="OP_CB_NOTIFY_DEVICEID_ARGUMENT" title="ARGUMENT | ||||
"> | ||||
<figure> | ||||
<artwork> | ||||
/* | /* | |||
* 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 41715 ¶ | skipping to change at line 41531 ¶ | |||
}; | }; | |||
/* For NOTIFY4_DEVICEID4_CHANGE */ | /* For NOTIFY4_DEVICEID4_CHANGE */ | |||
struct notify_deviceid_change4 { | struct notify_deviceid_change4 { | |||
layouttype4 ndc_layouttype; | layouttype4 ndc_layouttype; | |||
deviceid4 ndc_deviceid; | deviceid4 ndc_deviceid; | |||
bool ndc_immediate; | bool ndc_immediate; | |||
}; | }; | |||
struct CB_NOTIFY_DEVICEID4args { | struct CB_NOTIFY_DEVICEID4args { | |||
notify4 cnda_changes<>; | notify4 cnda_changes<>; | |||
}; | }; | |||
]]></sourcecode> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_CB_NOTIFY_DEVICEID_RESULT" numbered="t | |||
</section> | rue"> | |||
<section toc="exclude" anchor="OP_CB_NOTIFY_DEVICEID_RESULT" title="RESULT"> | <name>RESULT</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
struct CB_NOTIFY_DEVICEID4res { | struct CB_NOTIFY_DEVICEID4res { | |||
nfsstat4 cndr_status; | nfsstat4 cndr_status; | |||
}; | }; | |||
]]></sourcecode> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_CB_NOTIFY_DEVICEID_DESCRIPTION" number | |||
</section> | ed="true"> | |||
<section toc="exclude" anchor="OP_CB_NOTIFY_DEVICEID_DESCRIPTION" title="DESCR | <name>DESCRIPTION</name> | |||
IPTION"> | <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 | |||
changes to pNFS device IDs. The registration of | changes to pNFS device IDs. The registration of | |||
device ID notifications is optional and is done via | device ID notifications is optional and is done via | |||
GETDEVICEINFO. These notifications are sent | GETDEVICEINFO. These notifications are sent | |||
over the backchannel | over the backchannel | |||
once the original request has been processed | once the original request has been processed | |||
on the server. The server will send an array of | on the server. The server will send an array of | |||
notifications, cnda_changes, as a list of pairs of | notifications, cnda_changes, as a list of pairs of | |||
bitmaps and values. See <xref target="fattr4" /> | bitmaps and values. See <xref target="fattr4" format="default"/> | |||
for a description of how NFSv4.1 bitmaps work. | for a description of how NFSv4.1 bitmaps work. | |||
</t> | </t> | |||
<t> | ||||
<t> | As with CB_NOTIFY (<xref target="OP_CB_NOTIFY_DESCRIPTION" format="default"/ | |||
As with CB_NOTIFY (<xref | >), it is | |||
target="OP_CB_NOTIFY_DESCRIPTION"/>), it is | ||||
possible the server has more notifications than | possible the server has more notifications than | |||
can fit in a CB_COMPOUND, thus requiring multiple | can fit in a CB_COMPOUND, thus requiring multiple | |||
CB_COMPOUNDs. Unlike CB_NOTIFY, serialization is not | CB_COMPOUNDs. Unlike CB_NOTIFY, serialization is not | |||
an issue because unlike directory entries, device | an issue because unlike directory entries, device | |||
IDs cannot be re-used after being deleted (<xref | IDs cannot be re-used after being deleted (<xref target="device_ids" format= | |||
target="device_ids" />). | "default"/>). | |||
</t> | ||||
<t> | </t> | |||
<t> | ||||
All device ID notifications contain a device ID and a | All device ID notifications contain a device ID and a | |||
layout type. The layout type is necessary because two | layout type. The layout type is necessary because two | |||
different layout types can share the same device ID, | different layout types can share the same device ID, | |||
and the common device ID can have completely different | and the common device ID can have completely different | |||
mappings for each layout type. | mappings for each layout type. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
The server will send the following notifications: | The server will send the following notifications: | |||
<list style="hanging"> | </t> | |||
<dl newline="true" spacing="normal"> | ||||
<t hangText="NOTIFY_DEVICEID4_CHANGE"><vspace /> | <dt>NOTIFY_DEVICEID4_CHANGE</dt> | |||
<dd> | ||||
A previously provided device-ID-to-device-address | A previously provided device-ID-to-device-address | |||
mapping has changed and the client uses | mapping has changed and the client uses | |||
GETDEVICEINFO to obtain the | GETDEVICEINFO to obtain the | |||
updated mapping. | updated mapping. | |||
The notification is encoded in a value of data | The notification is encoded in a value of data | |||
type notify_deviceid_change4. This data type | type notify_deviceid_change4. This data type | |||
also contains a boolean field, ndc_immediate, | also contains a boolean field, ndc_immediate, | |||
which if TRUE indicates that the change will be | which if TRUE indicates that the change will be | |||
enforced immediately, and so the client might not | enforced immediately, and so the client might not | |||
be able to complete any pending I/O to the device | be able to complete any pending I/O to the device | |||
ID. If ndc_immediate is FALSE, then for an | ID. If ndc_immediate is FALSE, then for an | |||
indefinite time, the client can complete pending | indefinite time, the client can complete pending | |||
I/O. After pending I/O is complete, the client | I/O. After pending I/O is complete, the client | |||
SHOULD get the new device-ID-to-device-address | <bcp14>SHOULD</bcp14> get the new device-ID-to-device-address | |||
mappings before sending new I/O requests to the | mappings before sending new I/O requests to the | |||
storage devices addressed by the device ID. | storage devices addressed by the device ID. | |||
</t> | </dd> | |||
<dt>NOTIFY4_DEVICEID_DELETE</dt> | ||||
<t hangText="NOTIFY4_DEVICEID_DELETE"><vspace /> | <dd> | |||
<t> | ||||
Deletes a device ID from the mappings. This | Deletes a device ID from the mappings. This | |||
notification MUST NOT be sent if the client has | notification <bcp14>MUST NOT</bcp14> be sent if the client has | |||
a layout that refers to the device ID. In other | a layout that refers to the device ID. In other | |||
words, if the server is sending a delete device ID | words, if the server is sending a delete device ID | |||
notification, one of the following is true for layouts | notification, one of the following is true for layouts | |||
associated with the layout type: | associated with the layout type: | |||
<list style="symbols"> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <li> | |||
The client never had a layout referring to that device ID. | The client never had a layout referring to that device ID. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
The client has returned all layouts referring to that device ID. | The client has returned all layouts referring to that device ID. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
The server has revoked all layouts referring to that device ID. | The server has revoked all layouts referring to that device ID. | |||
</t> | </li> | |||
</ul> | ||||
</list> | <t> | |||
The notification is encoded in a value of data | The notification is encoded in a value of data | |||
type notify_deviceid_delete4. | type notify_deviceid_delete4. | |||
After a server deletes a device ID, it MUST NOT | 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> | |||
</list> | </dd> | |||
</t> | </dl> | |||
</section> | </section> | |||
</section> | ||||
</section> | <section anchor="OP_CB_ILLEGAL" numbered="true" toc="default"> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <name>Operation 10044: CB_ILLEGAL - Illegal Callback Operation</name> | |||
$ --> | <section toc="exclude" anchor="OP_CB_ILLEGAL_ARGUMENT" numbered="true"> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <name>ARGUMENT</name> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <sourcecode type="xdr"><![CDATA[ | |||
<section anchor="OP_CB_ILLEGAL" title="Operation 10044: CB_ILLEGAL - Illegal Cal | ||||
lback Operation" > | ||||
<section toc="exclude" anchor="OP_CB_ILLEGAL_ARGUMENT" title="ARGUMENT"> | ||||
<figure> | ||||
<artwork> | ||||
void; | void; | |||
</artwork> | ]]></sourcecode> | |||
</figure> | </section> | |||
</section> | <section toc="exclude" anchor="OP_CB_ILLEGAL_RESULT" numbered="true"> | |||
<section toc="exclude" anchor="OP_CB_ILLEGAL_RESULT" title="RESULT"> | <name>RESULT</name> | |||
<figure> | <sourcecode type="xdr"><![CDATA[ | |||
<artwork> | ||||
/* | /* | |||
* 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> | ||||
</artwork> | </section> | |||
</figure> | <section toc="exclude" anchor="OP_CB_ILLEGAL_DESCRIPTION" numbered="true | |||
</section> | "> | |||
<section toc="exclude" anchor="OP_CB_ILLEGAL_DESCRIPTION" title="DESCRIPTION"> | <name>DESCRIPTION</name> | |||
<t> | <t> | |||
This operation is a placeholder for encoding a | This operation is a placeholder for encoding a | |||
result to handle the case of the server sending | result to handle the case of the server sending | |||
an operation code within CB_COMPOUND that is not | an operation code within CB_COMPOUND that is not | |||
defined in the NFSv4.1 specification. See <xref | defined in the NFSv4.1 specification. See <xref target="OP_CB_COMPOUND_DESC | |||
target="OP_CB_COMPOUND_DESCRIPTION"/> for more details. | RIPTION" format="default"/> for more details. | |||
</t> | </t> | |||
<t> | <t> | |||
The status field of CB_ILLEGAL4res MUST be set to | The status field of CB_ILLEGAL4res <bcp14>MUST</bcp14> be set to | |||
NFS4ERR_OP_ILLEGAL. | NFS4ERR_OP_ILLEGAL. | |||
</t> | </t> | |||
</section> | </section> | |||
<section toc="exclude" anchor="OP_CB_ILLEGAL_IMPLEMENTATION" title="IMPLEMENTA | <section toc="exclude" anchor="OP_CB_ILLEGAL_IMPLEMENTATION" numbered="t | |||
TION"> | rue"> | |||
<t> | <name>IMPLEMENTATION</name> | |||
<t> | ||||
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> | |||
<!-- $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 | <section anchor="SECCON" numbered="true" toc="default"> | |||
$ --> | <name>Security Considerations</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <t> | |||
<!-- Copyright (C) The Internet Society (2006) --> | ||||
<section anchor="SECCON" title="Security Considerations"> | ||||
<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 | |||
RPC security flavor simply identified the end-user | RPC security flavor simply identified the end-user | |||
using the client to the NFS server. When processing | using the client to the NFS server. When processing | |||
NFS responses, the client ensured that the responses | NFS responses, the client ensured that the responses | |||
came from the same network address and port number | came from the same network address and port number | |||
to which the request was sent. While such a model is | to which the request was sent. While such a model is | |||
easy to implement and simple to deploy and use, it is | easy to implement and simple to deploy and use, it is | |||
unsafe. Thus, NFSv4.1 | unsafe. Thus, NFSv4.1 | |||
implementations are REQUIRED to support a security model that uses | implementations are <bcp14>REQUIRED</bcp14> to support a security model that uses | |||
end-to-end authentication, where an end-user on a client | end-to-end authentication, where an end-user on a client | |||
mutually authenticates (via cryptographic schemes that | mutually authenticates (via cryptographic schemes that | |||
do not expose passwords or keys in the clear on the | do not expose passwords or keys in the clear on the | |||
network) to a principal on an NFS server. Consideration | network) to a principal on an NFS server. Consideration | |||
is also given to the integrity and privacy of | is also given to the integrity and privacy of | |||
NFS requests and responses. The issues of end-to-end | NFS requests and responses. The issues of end-to-end | |||
mutual authentication, integrity, and privacy are | mutual authentication, integrity, and privacy are | |||
discussed in <xref target="RPCSEC_GSS_and_Security_Services" />. | discussed in <xref target="RPCSEC_GSS_and_Security_Services" format="default" />. | |||
There are specific considerations when using Kerberos V5 as described | There are specific considerations when using Kerberos V5 as described | |||
in <xref target="krb5_sec_consider"/>. | in <xref target="krb5_sec_consider" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
Note that being REQUIRED to implement does not mean REQUIRED to | Note that being <bcp14>REQUIRED</bcp14> to implement does not mean <bcp14>REQ | |||
UIRED</bcp14> to | ||||
use; AUTH_SYS can be used by NFSv4.1 clients and servers. | use; AUTH_SYS can be used by NFSv4.1 clients and servers. | |||
However, AUTH_SYS is merely an OPTIONAL security flavor in NFSv4.1, | However, AUTH_SYS is merely an <bcp14>OPTIONAL</bcp14> security flavor in NFS v4.1, | |||
and so interoperability via AUTH_SYS is not assured. | and so interoperability via AUTH_SYS is not assured. | |||
</t> | </t> | |||
<t> | <t> | |||
For reasons of reduced administration overhead, better | For reasons of reduced administration overhead, better | |||
performance, and/or reduction of CPU utilization, | performance, and/or reduction of CPU utilization, | |||
users of NFSv4.1 implementations might decline to use | users of NFSv4.1 implementations might decline to use | |||
security mechanisms that enable integrity protection | security mechanisms that enable integrity protection | |||
on each remote procedure call and response. The | on each remote procedure call and response. The | |||
use of mechanisms without integrity leaves the user | use of mechanisms without integrity leaves the user | |||
vulnerable to a man-in-the-middle of the NFS | vulnerable to a man-in-the-middle of the NFS | |||
client and server that modifies the RPC request and/or | client and server that modifies the RPC request and/or | |||
the response. While implementations are free to provide | the response. While implementations are free to provide | |||
the option to use weaker security mechanisms, there | the option to use weaker security mechanisms, there | |||
are three operations in particular that warrant the | are three operations in particular that warrant the | |||
implementation overriding user choices. | implementation overriding user choices. | |||
<list style='symbols'> | </t> | |||
<ul spacing="normal"> | ||||
<t> | <li> | |||
The first two such operations are SECINFO and | The first two such operations are SECINFO and | |||
SECINFO_NO_NAME. It is RECOMMENDED that the client send | SECINFO_NO_NAME. It is <bcp14>RECOMMENDED</bcp14> that the client send | |||
both operations such that they are protected with a | both operations such that they are protected with a | |||
security flavor that has integrity protection, such | security flavor that has integrity protection, such | |||
as RPCSEC_GSS with either the rpc_gss_svc_integrity | as RPCSEC_GSS with either the rpc_gss_svc_integrity | |||
or rpc_gss_svc_privacy service. Without integrity | or rpc_gss_svc_privacy service. Without integrity | |||
protection encapsulating SECINFO and SECINFO_NO_NAME | protection encapsulating SECINFO and SECINFO_NO_NAME | |||
and their results, a man-in-the-middle could | and their results, a man-in-the-middle could | |||
modify results such that the client might select a | modify results such that the client might select a | |||
weaker algorithm in the set allowed by the server, making | weaker algorithm in the set allowed by the server, making | |||
the client and/or server vulnerable to further attacks. | the client and/or server vulnerable to further attacks. | |||
</t> | </li> | |||
<t> | <li> | |||
The third operation that SHOULD use integrity protection | The third operation that <bcp14>SHOULD</bcp14> use integrity protection | |||
is any GETATTR for the fs_locations and fs_locations_info attributes, | is any GETATTR for the fs_locations and fs_locations_info attributes, | |||
in order to mitigate the severity of a man-in-the-middle attack. | in order to mitigate the severity of a man-in-the-middle attack. | |||
The attack has two | The attack has two | |||
steps. First the attacker modifies the unprotected results of some | steps. First the attacker modifies the unprotected results of some | |||
operation to return NFS4ERR_MOVED. Second, when the client follows up | operation to return NFS4ERR_MOVED. Second, when the client follows up | |||
with a GETATTR for the fs_locations or fs_locations_info attributes, | with a GETATTR for the fs_locations or fs_locations_info attributes, | |||
the attacker modifies | the attacker modifies | |||
the results to cause the client to migrate its traffic to a server | the results to cause the client to migrate its traffic to a server | |||
controlled by the attacker. With integrity protection, this attack is mitigat ed. | controlled by the attacker. With integrity protection, this attack is mitigat ed. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Relative to previous NFS versions, NFSv4.1 has additional security | Relative to previous NFS versions, NFSv4.1 has additional security | |||
considerations for pNFS (see Sections <xref target="security_considerations_pn | considerations for pNFS (see Sections <xref target="security_considerations_pn | |||
fs" format="counter" /> | fs" format="counter"/> | |||
and <xref target="file_security_considerations" format="counter" />), locking | and <xref target="file_security_considerations" format="counter"/>), locking | |||
and session state (see <xref target="protect_state_change"/>), | and session state (see <xref target="protect_state_change" format="default"/>) | |||
and state recovery during grace period (see <xref | , | |||
target="reclaim_security_considerations"/>). | and state recovery during grace period (see <xref target="reclaim_security_con | |||
siderations" format="default"/>). | ||||
With respect to locking and session state, if SP4_SSV state protection | With respect to locking and session state, if SP4_SSV state protection | |||
is being used, <xref target="rpcsec_ssv_consider"/> has specific | is being used, <xref target="rpcsec_ssv_consider" format="default"/> has speci fic | |||
security considerations for the NFSv4.1 client and server. | security considerations for the NFSv4.1 client and server. | |||
</t> | </t> | |||
<t> | <t> | |||
Security considerations for lock reclaim differ between the two different | Security considerations for lock reclaim differ between the two different | |||
situations in which state reclaim is to be done. | situations in which state reclaim is to be done. | |||
The server failure situation is discussed in | The server failure situation is discussed in | |||
<xref target="reclaim_security_considerations"/> while the per-fs state | <xref target="reclaim_security_considerations" format="default"/>, while the p er-fs state | |||
reclaim done in support of migration/replication is discussed in | reclaim done in support of migration/replication is discussed in | |||
<xref target="SEC11-EFF-lock-sc"/>. | <xref target="SEC11-EFF-lock-sc" format="default"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
The use of the multi-server namespace features described in | The use of the multi-server namespace features described in | |||
<xref target="NEW11"/> raises | <xref target="NEW11" format="default"/> raises | |||
the possibility that requests to determine the set of network | the possibility that requests to determine the set of network | |||
addresses corresponding to a given server might be interfered | addresses corresponding to a given server might be interfered | |||
with or have their responses modified in flight. | with or have their responses modified in flight. | |||
In light of this possibility, the following considerations | In light of this possibility, the following considerations | |||
should be taken note of: | should be noted: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
When DNS is used to convert server names to addresses and | When DNS is used to convert server names to addresses and | |||
DNSSEC <xref target="RFC4033"/> is not available, the validity of | DNSSEC <xref target="RFC4033" format="default"/> is not available, the val idity of | |||
the network addresses returned generally cannot be relied upon. | the network addresses returned generally cannot be relied upon. | |||
However, when combined with a trusted resolver, DNS over TLS | However, when combined with a trusted resolver, DNS over TLS | |||
<xref target="RFC7858"/>, and DNS over HTTPS | <xref target="RFC7858" format="default"/> and DNS over HTTPS | |||
<xref target="RFC8484"/> can also be relied upon to provide | <xref target="RFC8484" format="default"/> can be relied upon to provide | |||
valid address resolutions. | valid address resolutions. | |||
<vspace blankLines="1"/> | </t> | |||
<t> | ||||
In situations in which the validity of the provided addresses | In situations in which the validity of the provided addresses | |||
cannot be relied upon and the client uses RPCSEC_GSS to access the | cannot be relied upon and the client uses RPCSEC_GSS to access the | |||
designated server, it is possible for mutual authentication to | designated server, it is possible for mutual authentication to | |||
discover invalid server addresses as long as the RPCSEC_GSS | discover invalid server addresses as long as the RPCSEC_GSS | |||
implementation used does not use insecure DNS queries to canonicalize | implementation used does not use insecure DNS queries to canonicalize | |||
the hostname components of the service principal names, as | the hostname components of the service principal names, as | |||
explained in <xref target="RFC4120"/>. | explained in <xref target="RFC4120" format="default"/>. | |||
</t> | </t> | |||
<t> | </li> | |||
The fetching of | <li> | |||
attributes containing file system location information SHOULD be | The fetching of attributes containing file system location | |||
performed using integrity protection. | information <bcp14>SHOULD</bcp14> be | |||
It is important to note here that | performed using integrity protection. It is important to note here that | |||
a client making a request of this sort without using | a client making a request of this sort without using | |||
integrity protection needs be aware of | integrity protection needs be aware of | |||
the negative consequences of doing so, which can lead to | the negative consequences of doing so, which can lead to | |||
invalid host names or network addresses being returned. These | invalid hostnames or network addresses being returned. These | |||
include cases in which the | include cases in which the | |||
client is directed to a server under the control of an | client is directed to a server under the control of an | |||
attacker, who might get access to data written or provide | attacker, who might get access to data written or provide | |||
incorrect values for data read. | incorrect values for data read. In light of | |||
In light of | ||||
this, the client needs to recognize that using such returned | this, the client needs to recognize that using such returned | |||
location information to access an NFSv4 server | location information to access an NFSv4 server | |||
without use of RPCSEC_GSS (i.e. | without use of RPCSEC_GSS (i.e., | |||
by using AUTH_SYS) poses dangers as it can result in the client | by using AUTH_SYS) poses dangers as it can result in the client | |||
interacting with such an attacker-controlled server, without | interacting with such an attacker-controlled server without | |||
any authentication facilities to verify the server's identity. | any authentication facilities to verify the server's identity. | |||
</t> | </li> | |||
<t> | <li> | |||
Despite the fact that it is a requirement that | Despite the fact that it is a requirement that implementations provide | |||
implementations provide | ||||
"support" for use of RPCSEC_GSS, it cannot be assumed that | "support" for use of RPCSEC_GSS, it cannot be assumed that | |||
use of RPCSEC_GSS is always available between any particular | use of RPCSEC_GSS is always available between any particular | |||
client-server pair. | client-server pair. | |||
</t> | </li> | |||
<t> | <li> | |||
When a client has the network addresses of a server but not the | When a client has the network addresses of a server but not the | |||
associated host names, that would interfere with its ability | associated hostnames, that would interfere with its ability | |||
to use RPCSEC_GSS. | to use RPCSEC_GSS. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | In light of the above, a server <bcp14>SHOULD</bcp14> present file system loca | |||
In light of the above, a server SHOULD present file system location | tion | |||
entries that correspond to file systems on other servers using a | entries that correspond to file systems on other servers using a | |||
host name. This would allow the client to interrogate the | hostname. This would allow the client to interrogate the | |||
fs_locations on the destination server to obtain trunking information | fs_locations on the destination server to obtain trunking information | |||
(as well as replica information) using integrity protection, | (as well as replica information) using integrity protection, | |||
validating the name provided while assuring that the response has | validating the name provided while assuring that the response has | |||
not been modified in flight. | not been modified in flight. | |||
</t> | </t> | |||
<t> | <t> | |||
When RPCSEC_GSS is not available on a server, the client needs | When RPCSEC_GSS is not available on a server, the client needs | |||
to be aware of the fact that the location entries are subject to | to be aware of the fact that the location entries are subject to | |||
modification in flight and so cannot be relied upon. | modification in flight and so cannot be relied upon. | |||
In the case of a | In the case of a client being directed to another server after NFS4ERR_MOVED, | |||
client being directed to another server after NFS4ERR_MOVED, | ||||
this could vitiate the | this could vitiate the | |||
authentication provided by the use of RPCSEC_GSS on the designated | authentication provided by the use of RPCSEC_GSS on the designated | |||
destination server. | destination server. Even when RPCSEC_GSS authentication is available | |||
Even when RPCSEC_GSS authentication is available | ||||
on the destination, the server might still properly authenticate as the | on the destination, the server might still properly authenticate as the | |||
server to which the client was erroneously directed. | server to which the client was erroneously directed. | |||
Without a way to decide whether | Without a way to decide whether | |||
the server is a valid one, the client can only determine, using | the server is a valid one, the client can only determine, using | |||
RPCSEC_GSS, that the server corresponds to the name provided, with | RPCSEC_GSS, that the server corresponds to the name provided, with | |||
no basis for trusting that server. As a result, the client SHOULD | no basis for trusting that server. As a result, the client <bcp14>SHOULD | |||
NOT use such unverified location entries as a basis for migration, | NOT</bcp14> use such unverified location entries as a basis for migration, | |||
even though RPCSEC_GSS might be available on the destination. | even though RPCSEC_GSS might be available on the destination. | |||
</t> | </t> | |||
<t> | <t> | |||
When a file system location attribute is fetched | When a file system location attribute is fetched upon connecting with an | |||
upon connecting with an | NFS server, it <bcp14>SHOULD</bcp14>, as stated above, be done with integrity | |||
NFS server, it SHOULD, as stated above, be done with integrity protection. | protection. | |||
When this not possible, it is generally | When this not possible, it is generally | |||
best for the client to ignore trunking and replica information or | best for the client to ignore trunking and replica information or | |||
simply not fetch the location information for these purposes. | simply not fetch the location information for these purposes. | |||
</t> | </t> | |||
<t> | <t> | |||
When location information cannot be verified, it can be subjected | When location information cannot be verified, it can be subjected | |||
to additional filtering to prevent the client from being | to additional filtering to prevent the client from being | |||
inappropriately directed. For example, if a range of network | inappropriately directed. For example, if a range of network | |||
addresses can be determined that assure that the servers and | addresses can be determined that assure that the servers and | |||
clients using AUTH_SYS are subject to the appropriate set of | clients using AUTH_SYS are subject to the appropriate set of | |||
constraints (e.g. physical network isolation, administrative | constraints (e.g., physical network isolation, administrative | |||
controls on the operating systems used), then network addresses | controls on the operating systems used), then network addresses | |||
in the appropriate range can be used with others discarded | in the appropriate range can be used with others discarded | |||
or restricted in their use of AUTH_SYS. | or restricted in their use of AUTH_SYS. | |||
</t> | </t> | |||
<t> | <t> | |||
To summarize considerations regarding the use of RPCSEC_GSS in | To summarize considerations regarding the use of RPCSEC_GSS in | |||
fetching location information, we need to consider the following | fetching location information, we need to consider the following | |||
possibilities for requests to interrogate location information, with | possibilities for requests to interrogate location information, with | |||
interrogation approaches on the referring and destination servers | interrogation approaches on the referring and destination servers | |||
arrived at separately: | arrived at separately: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
The use of integrity protection is RECOMMENDED | <li> | |||
The use of integrity protection is <bcp14>RECOMMENDED</bcp14> | ||||
in all cases, since the absence of integrity protection exposes | in all cases, since the absence of integrity protection exposes | |||
the client to the possibility of the results | the client to the possibility of the results being modified in transit. | |||
being modified in transit. | </li> | |||
</t> | <li> | |||
<t> | ||||
The use of requests issued without RPCSEC_GSS | The use of requests issued without RPCSEC_GSS | |||
(i.e. using AUTH_SYS which has no provision to avoid | (i.e., using AUTH_SYS, which has no provision to avoid | |||
modification of data in flight), | modification of data in flight), | |||
while undesirable and a potential security exposure, | while undesirable and a potential security exposure, | |||
may not be avoidable in all cases. | may not be avoidable in all cases. Where the use | |||
Where the use | ||||
of the returned information cannot be avoided, it is made | of the returned information cannot be avoided, it is made | |||
subject to filtering as described above to | subject to filtering as described above to | |||
eliminate the possibility that the | eliminate the possibility that the client would | |||
client would | ||||
treat an invalid address as if it were a NFSv4 server. The | treat an invalid address as if it were a NFSv4 server. The | |||
specifics will vary depending on the degree of network isolation | specifics will vary depending on the degree of network isolation | |||
and whether the request is to the referring or destination servers. | and whether the request is to the referring or destination servers. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | ||||
Even if such requests are not interfered with in flight, it is possible | Even if such requests are not interfered with in flight, it is possible | |||
for a compromised server to direct the client to use inappropriate servers, | for a compromised server to direct the client to use inappropriate servers, | |||
such as those under the control of the attacker. It is not clear that being | such as those under the control of the attacker. It is not clear that being | |||
directed to such servers represents a greater threat to the client than the | directed to such servers represents a greater threat to the client than the | |||
damage that could be done by the compromised server itself. However, it | damage that could be done by the compromised server itself. However, it | |||
is possible that some sorts of transient server compromises might be taken | is possible that some sorts of transient server compromises might be | |||
advantage of to direct a client to a server capable of doing greater | exploited to direct a client to a server capable of doing greater | |||
damage over a longer time. One useful step to guard against this | damage over a longer time. One useful step to guard against this | |||
possibility is to issue requests to fetch location data using RPCSEC_GSS, | possibility is to issue requests to fetch location data using RPCSEC_GSS, | |||
even if no mapping to an RPCSEC_GSS principal is available. In this case, | even if no mapping to an RPCSEC_GSS principal is available. In this case, | |||
RPCSEC_GSS would not be used, as it typically is, to identify the client | RPCSEC_GSS would not be used, as it typically is, to identify the client | |||
principal to the server, but rather to make sure (via RPCSEC_GSS mutual | principal to the server, but rather to make sure (via RPCSEC_GSS mutual | |||
authentication) that the server being contacted is the one intended. | authentication) that the server being contacted is the one intended. | |||
</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> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | ||||
$ --> | <section anchor="ianaconsider" numbered="true" toc="default"> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <name>IANA Considerations</name> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <t> | |||
<section anchor="ianaconsider" | This section uses terms that are defined in <xref target="RFC8126" format="def | |||
title="IANA Considerations"> | ault"/>. | |||
<t> | ||||
This section uses terms that are defined in <xref target="RFC5226"/>. | ||||
</t> | </t> | |||
<section anchor="Iana-actions" | <section anchor="Iana-actions" numbered="true" toc="default"> | |||
title="IANA Actions Needed"> | <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, registr | |||
y | ||||
entries or registry rules associated with NFSv4.1. However, since | entries or registry rules associated with NFSv4.1. However, since | |||
this document is intended to obsolete RFC5661, it will be necessary | this document obsoletes RFC 5661, IANA has updated all registry entries an | |||
for IANA to update all registry entries and registry rules references | d registry rules references | |||
that points to RFC5661 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"/>. | subsections of <xref target="ianaconsider" format="default"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
<section anchor="namedattributesiana" | <section anchor="namedattributesiana" numbered="true" toc="default"> | |||
title="Named Attribute Definitions"> | <name>Named Attribute Definitions</name> | |||
<t> | <t> | |||
IANA created a registry called the "NFSv4 Named Attribute Definitions Regis try". | IANA created a registry called the "NFSv4 Named Attribute Definitions Regis try". | |||
</t> | </t> | |||
<t> | <t> | |||
The NFSv4.1 protocol supports the association of a file with zero or | The NFSv4.1 protocol supports the association of a file with zero or | |||
more named attributes. The namespace identifiers for these attributes | more named attributes. The namespace identifiers for these attributes | |||
are defined as string names. The protocol does not define the | are defined as string names. The protocol does not define the | |||
specific assignment of the namespace for these file attributes. | specific assignment of the namespace for these file attributes. | |||
The IANA registry promotes interoperability where common interests exist. | The IANA registry promotes interoperability where common interests exist. | |||
While application developers are allowed to define and use | While application developers are allowed to define and use | |||
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> | |||
<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 Section 4.1 of <xref target="RFC5226"/>. | 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 Section 4.1 of <xref target="RFC5226"/>. | 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^32 - 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, | |||
the prefixes of "EXPE" and "STDS" are Reserved. | the prefixes of "EXPE" and "STDS" are Reserved. | |||
The named attribute with a zero-length name is Reserved. | The named attribute with a zero-length name is Reserved. | |||
</t> | </t> | |||
<t> | <t> | |||
The prefix "PRIV" is designated for Private Use. A | The prefix "PRIV" is designated for Private Use. A | |||
site that wants to make use of unregistered named | site that wants to make use of unregistered named | |||
attributes without risk of conflicting with an | attributes without risk of conflicting with an | |||
assignment in IANA's registry should use the prefix | assignment in IANA's registry should use the prefix | |||
"PRIV" in all of its named attributes. | "PRIV" in all of its named attributes. | |||
</t> | ||||
</t> | <t> | |||
<t> | ||||
Because some NFSv4.1 clients and servers have case-insensitive | Because some NFSv4.1 clients and servers have case-insensitive | |||
semantics, the fifteen additional lower case and mixed case | semantics, the fifteen additional lower case and mixed case | |||
permutations of each of "EXPE", "PRIV", and "STDS" are Reserved (e.g., | permutations of each of "EXPE", "PRIV", and "STDS" are Reserved (e.g., | |||
"expe", "expE", "exPe", etc. are Reserved). | "expe", "expE", "exPe", etc. are Reserved). | |||
Similarly, IANA must not allow two assignments that would conflict | Similarly, IANA must not allow two assignments that would conflict | |||
if both named attributes were converted to a common case. | if both named attributes were converted to a common case. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
The registry of named attributes is a list of assignments, each | The registry of named attributes is a list of assignments, each | |||
containing three fields for each assignment. | containing three fields for each assignment. | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
A US-ASCII string name that is the actual name of | A US-ASCII string name that is the actual name of | |||
the attribute. This name must be unique. This | the attribute. This name must be unique. This | |||
string name can be 1 to 128 UTF-8 characters | string name can be 1 to 128 UTF-8 characters | |||
long. | long. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
A reference to the specification of the named attribute. | A reference to the specification of the named attribute. | |||
The reference can consume up to 256 bytes (or more if IANA | The reference can consume up to 256 bytes (or more if IANA | |||
permits). | permits). | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
The point of contact of the registrant. The point | The point of contact of the registrant. The point | |||
of contact can consume up to 256 bytes (or more if IANA | of contact can consume up to 256 bytes (or more if IANA | |||
permits). | permits). | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | <section numbered="true" toc="default"> | |||
<name>Initial Registry</name> | ||||
<section title="Initial Registry"> | <t> | |||
<t> | ||||
There is no initial registry. | There is no initial registry. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="Updating Registrations"> | <name>Updating Registrations</name> | |||
<t> | <t> | |||
The registrant is always permitted to update the point of contact | The registrant is always permitted to update the point of contact | |||
field. Any other change will require Expert Review or IESG | field. Any other change will require Expert Review or IESG | |||
Approval. | Approval. | |||
</t> | </t> | |||
</section> | </section> | |||
</section> | ||||
</section> | <section anchor="notifyiana" numbered="true" toc="default"> | |||
<name>Device ID Notifications</name> | ||||
<section anchor="notifyiana" title="Device ID Notifications"> | <t> | |||
<t> | ||||
IANA created a registry called the "NFSv4 Device ID | IANA created a registry called the "NFSv4 Device ID | |||
Notifications Registry". | Notifications Registry". | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
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 | added to the CB_NOTIFY_DEVICEID operation (see <xref target="OP_CB_NOTIFY_ | |||
target="OP_CB_NOTIFY_DEVICEID" />). This can be done | 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" />). | layout type (see <xref target="pnfsiana" format="default"/>). | |||
</t> | </t> | |||
<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 Section 4.1 of <xref target="RFC5226"/>, with | basis per <xref target="RFC8126" section="4.6" sectionFormat="of" format="d efault"/>, 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. | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
The name of the notification type. This name must have the | The name of the notification type. This name must have the | |||
prefix "NOTIFY_DEVICEID4_". This name must be unique. | prefix "NOTIFY_DEVICEID4_". This name must be unique. | |||
</t> | </li> | |||
<t> | <li> | |||
The value of the notification. IANA will assign | The value of the notification. IANA will assign | |||
this number, and the request from the registrant | this number, and the request from the registrant | |||
will use TBD1 instead of an actual value. IANA | will use TBD1 instead of an actual value. IANA | |||
MUST use a whole number that can be no higher | <bcp14>MUST</bcp14> use a whole number that can be no higher | |||
than 2^32-1, and should be the next available | than 2<sup>32</sup>-1, and should be the next available | |||
value. The value assigned must be unique. | value. The value assigned must be unique. | |||
A Designated Expert must be used to | A Designated Expert must be used to | |||
ensure that when the name of the notification | ensure that when the name of the notification | |||
type and its value are added to the NFSv4.1 | type and its value are added to the NFSv4.1 | |||
notify_deviceid_type4 enumerated data type in the | notify_deviceid_type4 enumerated data type in the | |||
NFSv4.1 XDR description (<xref | NFSv4.1 XDR description <xref target="RFC5662" format="default"/>, the | |||
target="RFC5662"/>), the result continues to | result continues to | |||
be a valid XDR description. | be a valid XDR description. | |||
</li> | ||||
</t> | <li> | |||
<t> | ||||
The Standards Track RFC(s) that describe the | The Standards Track RFC(s) that describe the | |||
notification. If the RFC(s) have not yet been | notification. If the RFC(s) have not yet been | |||
published, the registrant will use RFCTBD2, RFCTBD3, etc. instead | published, the registrant will use RFCTBD2, RFCTBD3, etc. instead | |||
of an actual RFC number. | of an actual RFC number. | |||
</li> | ||||
</t> | <li> | |||
<t> | ||||
How the RFC introduces the notification. This is | How the RFC introduces the notification. This is | |||
indicated by a single US-ASCII value. If the | indicated by a single US-ASCII value. If the | |||
value is N, it means a minor revision to the | value is N, it means a minor revision to the | |||
NFSv4 protocol. If the value is L, it means a new | NFSv4 protocol. If the value is L, it means a new | |||
pNFS layout type. Other values can be used with | pNFS layout type. Other values can be used with | |||
IESG Approval. | IESG Approval. | |||
</li> | ||||
</t> | <li> | |||
<t> | ||||
The minor versions of NFSv4 that are allowed to | The minor versions of NFSv4 that are allowed to | |||
use the notification. While these are numeric | use the notification. While these are numeric | |||
values, IANA will not allocate and assign them; | values, IANA will not allocate and assign them; | |||
the author of the relevant RFCs with IESG | the author of the relevant RFCs with IESG | |||
Approval assigns these numbers. Each time there is a | Approval assigns these numbers. Each time there is a | |||
new minor version of NFSv4 approved, a Designated | new minor version of NFSv4 approved, a Designated | |||
Expert should review the registry to make recommended | Expert should review the registry to make recommended | |||
updates as needed. | updates as needed. | |||
</li> | ||||
</t> | </ol> | |||
</list> | <section numbered="true" toc="default"> | |||
</t> | <name>Initial Registry</name> | |||
<t> | ||||
<section title="Initial Registry"> | The initial registry is in <xref target="devnotelist" format="default"/>. Not | |||
<t> | e that the | |||
The initial registry is in <xref target="devnotelist"/>. Note that the | ||||
next available value is zero. | next available value is zero. | |||
</t> | </t> | |||
<table anchor="devnotelist" align="center"> | ||||
<texttable title="Initial Device ID Notification Assignments" anchor='devnotel | <name>Initial Device ID Notification Assignments</name> | |||
ist'> | <thead> | |||
<tr> | ||||
<ttcol>Notification Name</ttcol> | <th align="left">Notification Name</th> | |||
<ttcol>Value</ttcol> | <th align="left">Value</th> | |||
<ttcol>RFC</ttcol> | <th align="left">RFC</th> | |||
<ttcol>How</ttcol> | <th align="left">How</th> | |||
<ttcol>Minor Versions</ttcol> | <th align="left">Minor Versions</th> | |||
</tr> | ||||
<c>NOTIFY_DEVICEID4_CHANGE</c> <c>1</c> <c>RFC5661</c> <c>N</c> <c>1</c> | </thead> | |||
<tbody> | ||||
<c>NOTIFY_DEVICEID4_DELETE</c> <c>2</c> <c>RFC5661</c> <c>N</c> <c>1</c> | <tr> | |||
<td align="left">NOTIFY_DEVICEID4_CHANGE</td> | ||||
</texttable> | <td align="left">1</td> | |||
<td align="left">RFC 8881</td> | ||||
</section> | <td align="left">N</td> | |||
<td align="left">1</td> | ||||
<section title="Updating Registrations"> | </tr> | |||
<t> | <tr> | |||
<td align="left">NOTIFY_DEVICEID4_DELETE</td> | ||||
<td align="left">2</td> | ||||
<td align="left">RFC 8881</td> | ||||
<td align="left">N</td> | ||||
<td align="left">1</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
</section> | ||||
<section numbered="true" toc="default"> | ||||
<name>Updating Registrations</name> | ||||
<t> | ||||
The update of a registration will require IESG | The update of a registration will require IESG | |||
Approval on the advice of a Designated Expert. | Approval on the advice of a Designated Expert. | |||
</t> | </t> | |||
</section> | ||||
</section> | </section> | |||
</section> | <section anchor="recalliana" numbered="true" toc="default"> | |||
<name>Object Recall Types</name> | ||||
<section anchor="recalliana" title="Object Recall Types"> | <t> | |||
<t> | ||||
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" />). 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 tar | add a new recallable object is to specify a new layout type (see <xref tar | |||
get="pnfsiana" />). | get="pnfsiana" format="default"/>). | |||
</t> | </t> | |||
<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 Section 4.1 of <xref target="RFC5226"/>, 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 Pri vate | values. Values in the range 12 through 15, inclusive, are designated for Pri vate | |||
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. | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
The name of the recallable object type. This name must have the | The name of the recallable object type. This name must have the | |||
prefix "RCA4_TYPE_MASK_". The name must be unique. | prefix "RCA4_TYPE_MASK_". The name must be unique. | |||
</t> | </li> | |||
<t> | <li> | |||
The value of the recallable object type. IANA | The value of the recallable object type. IANA | |||
will assign this number, and the request from the | will assign this number, and the request from the | |||
registrant will use TBD1 instead of an actual | registrant will use TBD1 instead of an actual | |||
value. IANA MUST use a whole number that can be | value. IANA <bcp14>MUST</bcp14> use a whole number that can be | |||
no higher than 2^32-1, and should be the next | no higher than 2<sup>32</sup>-1, and should be the next | |||
available value. The value must be unique. A | available value. The value must be unique. A | |||
Designated Expert must be used to ensure that | Designated Expert must be used to ensure that | |||
when the name of the recallable type and its | when the name of the recallable type and its | |||
value are added to the NFSv4 XDR description | value are added to the NFSv4 XDR description | |||
<xref target="RFC5662"/>, | <xref target="RFC5662" format="default"/>, | |||
the result continues to be a valid XDR | the result continues to be a valid XDR | |||
description. | description. | |||
</li> | ||||
</t> | <li> | |||
<t> | ||||
The Standards Track RFC(s) that describe the | The Standards Track RFC(s) that describe the | |||
recallable object type. If the RFC(s) have not yet been | recallable object type. If the RFC(s) have not yet been | |||
published, the registrant will use RFCTBD2, RFCTBD3, etc. instead | published, the registrant will use RFCTBD2, RFCTBD3, etc. instead | |||
of an actual RFC number. | of an actual RFC number. | |||
</li> | ||||
</t> | <li> | |||
<t> | ||||
How the RFC introduces the recallable object type. This is | How the RFC introduces the recallable object type. This is | |||
indicated by a single US-ASCII value. If the | indicated by a single US-ASCII value. If the | |||
value is N, it means a minor revision to the | value is N, it means a minor revision to the | |||
NFSv4 protocol. If the value is L, it means a new | NFSv4 protocol. If the value is L, it means a new | |||
pNFS layout type. Other values can be used with | pNFS layout type. Other values can be used with | |||
IESG Approval. | IESG Approval. | |||
</li> | ||||
</t> | <li> | |||
<t> | ||||
The minor versions of NFSv4 that are allowed to | The minor versions of NFSv4 that are allowed to | |||
use the recallable object type. While these | use the recallable object type. While these | |||
are numeric values, IANA will not allocate and | are numeric values, IANA will not allocate and | |||
assign them; the author of the relevant RFCs with | assign them; the author of the relevant RFCs with | |||
IESG Approval assigns these numbers. Each time | IESG Approval assigns these numbers. Each time | |||
there is a new minor version of NFSv4 approved, a | there is a new minor version of NFSv4 approved, a | |||
Designated Expert should review the registry to | Designated Expert should review the registry to | |||
make recommended updates as needed. | make recommended updates as needed. | |||
</li> | ||||
</t> | </ol> | |||
</list> | <section numbered="true" toc="default"> | |||
</t> | <name>Initial Registry</name> | |||
<t> | ||||
<section title="Initial Registry"> | The initial registry is in <xref target="recalllist" format="default"/>. Note | |||
<t> | that | |||
The initial registry is in <xref target="recalllist"/>. Note that | ||||
the next available value is five. | the next available value is five. | |||
</t> | </t> | |||
<table anchor="recalllist" align="center"> | ||||
<texttable title="Initial Recallable Object Type Assignments" anchor='recallli | <name>Initial Recallable Object Type Assignments</name> | |||
st'> | <thead> | |||
<tr> | ||||
<ttcol>Recallable Object Type Name</ttcol> | <th align="left">Recallable Object Type Name</th> | |||
<ttcol>Value</ttcol> | <th align="left">Value</th> | |||
<ttcol>RFC</ttcol> | <th align="left">RFC</th> | |||
<ttcol>How</ttcol> | <th align="left">How</th> | |||
<ttcol>Minor Versions</ttcol> | <th align="left">Minor Versions</th> | |||
</tr> | ||||
<c>RCA4_TYPE_MASK_RDATA_DLG</c> <c>0</c> <c>RFC 5661</c> <c>N</c> <c>1</c | </thead> | |||
> | <tbody> | |||
<tr> | ||||
<c>RCA4_TYPE_MASK_WDATA_DLG</c> <c>1</c> <c>RFC 5661</c> <c>N</c> <c>1</c | <td align="left">RCA4_TYPE_MASK_RDATA_DLG</td> | |||
> | <td align="left">0</td> | |||
<td align="left">RFC 8881</td> | ||||
<c>RCA4_TYPE_MASK_DIR_DLG</c> <c>2</c> <c>RFC 5661</c> <c>N</c> <c>1</c> | <td align="left">N</td> | |||
<td align="left">1</td> | ||||
<c>RCA4_TYPE_MASK_FILE_LAYOUT</c> <c>3</c> <c>RFC 5661</c> <c>N</c> <c>1< | </tr> | |||
/c> | <tr> | |||
<td align="left">RCA4_TYPE_MASK_WDATA_DLG</td> | ||||
<c>RCA4_TYPE_MASK_BLK_LAYOUT</c> <c>4</c> <c>RFC 5661</c> <c>L</c> <c>1</ | <td align="left">1</td> | |||
c> | <td align="left">RFC 8881</td> | |||
<td align="left">N</td> | ||||
<c>RCA4_TYPE_MASK_OBJ_LAYOUT_MIN</c> <c>8</c> <c>RFC 5661</c> <c>L</c> <c | <td align="left">1</td> | |||
>1</c> | </tr> | |||
<c>RCA4_TYPE_MASK_OBJ_LAYOUT_MAX</c> <c>9</c> <c>RFC 5661</c> <c>L</c> <c | <tr> | |||
>1</c> | <td align="left">RCA4_TYPE_MASK_DIR_DLG</td> | |||
<td align="left">2</td> | ||||
</texttable> | <td align="left">RFC 8881</td> | |||
<td align="left">N</td> | ||||
</section> | <td align="left">1</td> | |||
</tr> | ||||
<section title="Updating Registrations"> | <tr> | |||
<t> | <td align="left">RCA4_TYPE_MASK_FILE_LAYOUT</td> | |||
<td align="left">3</td> | ||||
<td align="left">RFC 8881</td> | ||||
<td align="left">N</td> | ||||
<td align="left">1</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">RCA4_TYPE_MASK_BLK_LAYOUT</td> | ||||
<td align="left">4</td> | ||||
<td align="left">RFC 8881</td> | ||||
<td align="left">L</td> | ||||
<td align="left">1</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">RCA4_TYPE_MASK_OBJ_LAYOUT_MIN</td> | ||||
<td align="left">8</td> | ||||
<td align="left">RFC 8881</td> | ||||
<td align="left">L</td> | ||||
<td align="left">1</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">RCA4_TYPE_MASK_OBJ_LAYOUT_MAX</td> | ||||
<td align="left">9</td> | ||||
<td align="left">RFC 8881</td> | ||||
<td align="left">L</td> | ||||
<td align="left">1</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
</section> | ||||
<section numbered="true" toc="default"> | ||||
<name>Updating Registrations</name> | ||||
<t> | ||||
The update of a registration will require IESG | The update of a registration will require IESG | |||
Approval on the advice of a Designated Expert. | Approval on the advice of a Designated Expert. | |||
</t> | </t> | |||
</section> | ||||
</section> | </section> | |||
</section> | <section anchor="pnfsiana" numbered="true" toc="default"> | |||
<name>Layout Types</name> | ||||
<section anchor="pnfsiana" title="Layout Types"> | <t> | |||
<t> | ||||
IANA created a registry called the "pNFS Layout Types Registry". | IANA created a registry called the "pNFS Layout Types Registry". | |||
</t> | </t> | |||
<t> | <t> | |||
All assignments to the registry are made on a Standards Action basis, | All assignments to the registry are made on a Standards Action basis, | |||
with Expert Review required. | with Expert Review required. | |||
</t> | </t> | |||
<t> | <t> | |||
Layout types are 32-bit numbers. The value zero is Reserved. | Layout types are 32-bit numbers. The value zero is Reserved. | |||
Values in the range 0x80000000 to 0xFFFFFFFF inclusive are designated for Private Use. | Values in the range 0x80000000 to 0xFFFFFFFF inclusive are designated for Private Use. | |||
IANA will assign numbers from the range | IANA will assign numbers from the range | |||
0x00000001 to 0x7FFFFFFF inclusive. | 0x00000001 to 0x7FFFFFFF inclusive. | |||
</t> | </t> | |||
<t> | <t> | |||
The registry is a list of assignments, each | The registry is a list of assignments, each | |||
containing five fields. | containing five fields. | |||
</t> | ||||
<list style='numbers'> | <ol spacing="normal" type="1"> | |||
<t> | <li> | |||
The name of the layout type. This name must have the | The name of the layout type. This name must have the | |||
prefix "LAYOUT4_". The name must be unique. | prefix "LAYOUT4_". The name must be unique. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
The value of the layout type. IANA will assign | The value of the layout type. IANA will assign | |||
this number, and the request from the registrant | this number, and the request from the registrant | |||
will use TBD1 instead of an actual value. The value | will use TBD1 instead of an actual value. The value | |||
assigned must be unique. | assigned must be unique. | |||
A Designated Expert must be used to ensure | A Designated Expert must be used to ensure | |||
that when the name of the layout type and | that when the name of the layout type and | |||
its value are added to the NFSv4.1 layouttype4 | its value are added to the NFSv4.1 layouttype4 | |||
enumerated data type in the NFSv4.1 XDR | enumerated data type in the NFSv4.1 XDR | |||
description (<xref | description <xref target="RFC5662" format="default"/>, | |||
target="RFC5662"/>), | ||||
the result continues to be a valid XDR | the result continues to be a valid XDR | |||
description. | description. | |||
</li> | ||||
</t> | <li> | |||
<t> | ||||
The Standards Track RFC(s) that describe the | The Standards Track RFC(s) that describe the | |||
notification. If the RFC(s) have not yet been | notification. If the RFC(s) have not yet been | |||
published, the registrant will use RFCTBD2, RFCTBD3, etc. instead | published, the registrant will use RFCTBD2, RFCTBD3, etc. instead | |||
of an actual RFC number. Collectively, the RFC(s) must adhere to | of an actual RFC number. Collectively, the RFC(s) must adhere to | |||
the guidelines listed in <xref target="layout_guidelines"/>. | the guidelines listed in <xref target="layout_guidelines" format="defa | |||
ult"/>. | ||||
</t> | </li> | |||
<li> | ||||
<t> | ||||
How the RFC introduces the layout type. This is | How the RFC introduces the layout type. This is | |||
indicated by a single US-ASCII value. If the | indicated by a single US-ASCII value. If the | |||
value is N, it means a minor revision to the | value is N, it means a minor revision to the | |||
NFSv4 protocol. If the value is L, it means a new | NFSv4 protocol. If the value is L, it means a new | |||
pNFS layout type. Other values can be used with | pNFS layout type. Other values can be used with | |||
IESG Approval. | IESG Approval. | |||
</li> | ||||
</t> | <li> | |||
<t> | ||||
The minor versions of NFSv4 that are allowed to | The minor versions of NFSv4 that are allowed to | |||
use the notification. While these are numeric | use the notification. While these are numeric | |||
values, IANA will not allocate and assign them; | values, IANA will not allocate and assign them; | |||
the author of the relevant RFCs with IESG | the author of the relevant RFCs with IESG | |||
Approval assigns these numbers. Each time there is | Approval assigns these numbers. Each time there is | |||
a new minor version of NFSv4 approved, a Designated | a new minor version of NFSv4 approved, a Designated | |||
Expert should review the registry to make recommended | Expert should review the registry to make recommended | |||
updates as needed. | updates as needed. | |||
</li> | ||||
</t> | </ol> | |||
<section numbered="true" toc="default"> | ||||
</list> | <name>Initial Registry</name> | |||
<t> | ||||
</t> | The initial registry is in <xref target="layoutlist" format="default"/>. | |||
</t> | ||||
<section title="Initial Registry"> | <table anchor="layoutlist" align="center"> | |||
<t> | <name>Initial Layout Type Assignments</name> | |||
The initial registry is in <xref target="layoutlist"/>. | <thead> | |||
</t> | <tr> | |||
<th align="left">Layout Type Name</th> | ||||
<texttable title="Initial Layout Type Assignments" anchor='layoutlist'> | <th align="left">Value</th> | |||
<th align="left">RFC</th> | ||||
<ttcol>Layout Type Name</ttcol> | <th align="left">How</th> | |||
<ttcol>Value</ttcol> | <th align="left">Minor Versions</th> | |||
<ttcol>RFC</ttcol> | </tr> | |||
<ttcol>How</ttcol> | </thead> | |||
<ttcol>Minor Versions</ttcol> | <tbody> | |||
<tr> | ||||
<c>LAYOUT4_NFSV4_1_FILES</c> <c>0x1</c> <c>RFC 5661</c> <c>N</c> <c>1</c | <td align="left">LAYOUT4_NFSV4_1_FILES</td> | |||
> | <td align="left">0x1</td> | |||
<td align="left">RFC 8881</td> | ||||
<c>LAYOUT4_OSD2_OBJECTS</c> <c>0x2</c> <c>RFC 5664</c> <c>L</c> <c>1</c> | <td align="left">N</td> | |||
<c>LAYOUT4_BLOCK_VOLUME</c> <c>0x3</c> <c>RFC 5663</c> <c>L</c> <c>1</c> | <td align="left">1</td> | |||
<!-- [rfced] The IANA site lists this document (RFC 5661) as the | </tr> | |||
reference for values 0x2 and 0x3, instead of RFCs 5664 and 5663, | <tr> | |||
respectively. Does the IANA site need to be updated? | <td align="left">LAYOUT4_OSD2_OBJECTS</td> | |||
<td align="left">0x2</td> | ||||
[Eisler]: The IANA site needs to be updated. --> | <td align="left">RFC 5664</td> | |||
</texttable> | <td align="left">L</td> | |||
<td align="left">1</td> | ||||
</section> | </tr> | |||
<tr> | ||||
<section title="Updating Registrations"> | <td align="left">LAYOUT4_BLOCK_VOLUME</td> | |||
<t> | <td align="left">0x3</td> | |||
<td align="left">RFC 5663</td> | ||||
<td align="left">L</td> | ||||
<td align="left">1</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
</section> | ||||
<section numbered="true" toc="default"> | ||||
<name>Updating Registrations</name> | ||||
<t> | ||||
The update of a registration will require IESG | The update of a registration will require IESG | |||
Approval on the advice of a Designated Expert. | Approval on the advice of a Designated Expert. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section anchor="layout_guidelines" numbered="true" toc="default"> | |||
<name>Guidelines for Writing Layout Type Specifications</name> | ||||
<section anchor="layout_guidelines" title="Guidelines for Writing Layout Typ | <t> | |||
e Specifications"> | ||||
<t> | ||||
The author of a new pNFS layout specification must follow these | The author of a new pNFS layout specification must follow these | |||
steps to obtain acceptance of the layout type as a Standards Track RFC: | steps to obtain acceptance of the layout type as a Standards Track RFC: | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
The author devises the new layout specification. | The author devises the new layout specification. | |||
</t> | </li> | |||
<t> | <li> | |||
The new layout type specification MUST, at a minimum: | <t> | |||
<list style='symbols'> | The new layout type specification <bcp14>MUST</bcp14>, at a minimum: | |||
<t> | </t> | |||
<ul spacing="normal"> | ||||
<li> | ||||
<t> | ||||
Define the contents of the layout-type-specific fields of the | Define the contents of the layout-type-specific fields of the | |||
following data types: | following data types: | |||
<list style='symbols'> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
the da_addr_body field of the device_addr4 | the da_addr_body field of the device_addr4 | |||
data type; | data type; | |||
</t> | </li> | |||
<t> | <li> | |||
the loh_body field of the layouthint4 | the loh_body field of the layouthint4 | |||
data type; | data type; | |||
</t> | </li> | |||
<t> | <li> | |||
the loc_body field of layout_content4 | the loc_body field of layout_content4 | |||
data type (which in turn is the lo_content field of the | data type (which in turn is the lo_content field of the | |||
layout4 data type); | layout4 data type); | |||
</t> | </li> | |||
<t> | <li> | |||
the lou_body field of the layoutupdate4 | the lou_body field of the layoutupdate4 | |||
data type; | data type; | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </li> | |||
<t> | <li> | |||
Describe or define the storage access protocol used to access | Describe or define the storage access protocol used to access | |||
the storage devices. | the storage devices. | |||
</t> | </li> | |||
<t> | <li> | |||
Describe whether revocation of layouts is supported. | Describe whether revocation of layouts is supported. | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
At a minimum, describe the methods of recovery from: | At a minimum, describe the methods of recovery from: | |||
<list style="numbers"> | </t> | |||
<t> Failure and restart for client, server, storage device. | <ol spacing="normal" type="1"> | |||
</t> | <li> Failure and restart for client, server, storage device. | |||
<t> Lease expiration from perspective of the active client, | </li> | |||
<li> Lease expiration from perspective of the active client, | ||||
server, storage device. | server, storage device. | |||
</t> | </li> | |||
<t> Loss of layout state resulting in fencing of client | <li> Loss of layout state resulting in fencing of client | |||
access to storage devices (for an example, see | access to storage devices (for an example, see | |||
<xref target="lease_expiration_mds" />). | <xref target="lease_expiration_mds" format="default"/>). | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | </li> | |||
<t> | <li> | |||
<t> | ||||
Include an IANA considerations section, which will | Include an IANA considerations section, which will | |||
in turn include: | in turn include: | |||
</t> | ||||
<list style="symbols"> | <ul spacing="normal"> | |||
<t> | <li> | |||
A request to IANA | A request to IANA | |||
for a new layout type per <xref | for a new layout type per <xref target="pnfsiana" format="default | |||
target="pnfsiana"/>. | "/>. | |||
</li> | ||||
</t> | <li> | |||
<t> | ||||
A list of requests to IANA for | A list of requests to IANA for | |||
any new recallable object types for | any new recallable object types for | |||
CB_RECALL_ANY; each entry is to be presented in the form describe d | CB_RECALL_ANY; each entry is to be presented in the form describe d | |||
in <xref target="recalliana"/>. | in <xref target="recalliana" format="default"/>. | |||
</li> | ||||
</t> | <li> | |||
<t> | ||||
A list of requests to IANA for | A list of requests to IANA for | |||
any new notification values for | any new notification values for | |||
CB_NOTIFY_DEVICEID; each entry is to be presented in the form | CB_NOTIFY_DEVICEID; each entry is to be presented in the form | |||
described in <xref target="notifyiana"/>. | described in <xref target="notifyiana" format="default"/>. | |||
</li> | ||||
</t> | </ul> | |||
</list> | </li> | |||
<li> | ||||
</t> | Include a security considerations section. This section <bcp14>MUST | |||
<t> | </bcp14> | |||
Include a security considerations section. This section MUST | ||||
explain how the NFSv4.1 authentication, authorization, and | explain how the NFSv4.1 authentication, authorization, and | |||
access-control models are preserved. That is, if a metadata server | access-control models are preserved. That is, if a metadata server | |||
would restrict a READ or WRITE operation, how would pNFS via | would restrict a READ or WRITE operation, how would pNFS via | |||
the layout similarly restrict a corresponding input or | the layout similarly restrict a corresponding input or | |||
output operation? | output operation? | |||
</t> | </li> | |||
</ul> | ||||
</list> | </li> | |||
</t> | <li> | |||
<t> | ||||
The author documents the new layout specification as an Internet-Draft. | The author documents the new layout specification as an Internet-Draft. | |||
</t> | </li> | |||
<t> | ||||
<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. | |||
</t> | </li> | |||
<t> | <li> | |||
The layout specification progresses through the IETF standards | The layout specification progresses through the IETF standards | |||
process. | process. | |||
</t> | </li> | |||
</list> | </ol> | |||
</t> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="path_var_iana" numbered="true" toc="default"> | |||
<name>Path Variable Definitions</name> | ||||
<section anchor="path_var_iana" title="Path Variable Definitions"> | <t> | |||
<t> | ||||
This section deals with the IANA considerations associated with | This section deals with the IANA considerations associated with | |||
the variable substitution feature for location names as | the variable substitution feature for location names as | |||
described in <xref target="SEC11-fsli-item" />. As | described in <xref target="SEC11-fsli-item" format="default"/>. As | |||
described there, variables subject to substitution consist | described there, variables subject to substitution consist | |||
of a domain name and a specific name within that domain, with the | of a domain name and a specific name within that domain, with the | |||
two separated by a colon. There are two sets of IANA considerations | two separated by a colon. There are two sets of IANA considerations | |||
here: | here: | |||
<list style='numbers'> | ||||
<t> | ||||
The list of variable names. | ||||
</t> | </t> | |||
<ol spacing="normal" type="1"> | ||||
<t> | <li> | |||
The list of variable names. | ||||
</li> | ||||
<li> | ||||
For each variable name, the list of possible values. | For each variable name, the list of possible values. | |||
</t> | </li> | |||
</ol> | ||||
</list> | <t> | |||
Thus, there will be one registry for the list of variable names, and | Thus, there will be one registry for the list of variable names, and | |||
possibly one registry for listing the values of each variable name. | possibly one registry for listing the values of each variable name. | |||
</t> | </t> | |||
<section anchor="path_variables_iana" numbered="true" toc="default"> | ||||
<section anchor="path_variables_iana" title="Path Variables Registry"> | <name>Path Variables Registry</name> | |||
<t> | <t> | |||
IANA created a registry called the "NFSv4 Path Variables Registry". | IANA created a registry called the "NFSv4 Path Variables Registry". | |||
</t> | </t> | |||
<section anchor="path_values_iana" numbered="true" toc="default"> | ||||
<section anchor="path_values_iana" title="Path Variable Values"> | <name>Path Variable Values</name> | |||
<t> | <t> | |||
Variable names are of the form "${", followed by a | Variable names are of the form "${", followed by a | |||
domain name, followed by a colon (":"), followed by | domain name, followed by a colon (":"), followed by | |||
a domain-specific portion of the variable name, | a domain-specific portion of the variable name, | |||
followed by "}". When the domain name is "ietf.org", | followed by "}". When the domain name is "ietf.org", | |||
all variables names must be registered with IANA on | all variables names must be registered with IANA on | |||
a Standards Action basis, with Expert Review | a Standards Action basis, with Expert Review | |||
required. Path variables with registered domain | required. Path variables with registered domain | |||
names neither part of nor equal to ietf.org are | names neither part of nor equal to ietf.org are | |||
assigned on a Hierarchical Allocation basis | assigned on a Hierarchical Allocation basis | |||
(delegating to the domain owner) and thus of no | (delegating to the domain owner) and thus of no | |||
skipping to change at line 42776 ¶ | skipping to change at line 42596 ¶ | |||
domain owner chooses to do so, IANA will do so on a | domain owner chooses to do so, IANA will do so on a | |||
First Come First Serve basis. To accommodate | First Come First Serve basis. To accommodate | |||
registrants who do not have their own domain, IANA | registrants who do not have their own domain, IANA | |||
will accept requests to register variables with the | will accept requests to register variables with the | |||
prefix "${FCFS.ietf.org:" on a First Come First | prefix "${FCFS.ietf.org:" on a First Come First | |||
Served basis. Assignments on a First Come First Basis | Served basis. Assignments on a First Come First Basis | |||
do not require Expert Review, unless the registrant also | do not require Expert Review, unless the registrant also | |||
wants IANA to establish a registry for the values of the | wants IANA to establish a registry for the values of the | |||
registered variable. | registered variable. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
The registry is a list of assignments, each | The registry is a list of assignments, each | |||
containing three fields. | containing three fields. | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
The name of the variable. The name of this | The name of the variable. The name of this | |||
variable must start with a "${" followed by a | variable must start with a "${" followed by a | |||
registered domain name, followed by ":", or it | registered domain name, followed by ":", or it | |||
must start with "${FCFS.ietf.org". The name must | must start with "${FCFS.ietf.org". The name must | |||
be no more than 64 UTF-8 characters long. The | be no more than 64 UTF-8 characters long. The | |||
name must be unique. | name must be unique. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
For assignments made on Standards Action basis, | For assignments made on Standards Action basis, | |||
the Standards Track RFC(s) that describe the | the Standards Track RFC(s) that describe the | |||
variable. If the RFC(s) have not yet been | variable. If the RFC(s) have not yet been | |||
published, the registrant will use RFCTBD1, | published, the registrant will use RFCTBD1, | |||
RFCTBD2, etc. instead of an actual RFC number. | RFCTBD2, etc. instead of an actual RFC number. | |||
Note that the RFCs do not have to be a part of an NFS minor version. | Note that the RFCs do not have to be a part of an NFS minor version. | |||
For assignments made on a First Come First Serve basis, an explanation | For assignments made on a First Come First Serve basis, an explanation | |||
(consuming no more than 1024 bytes, or more if IANA permits) | (consuming no more than 1024 bytes, or more if IANA permits) | |||
of the purpose of the variable. A reference to the explanation can | of the purpose of the variable. A reference to the explanation can | |||
be substituted. | be substituted. | |||
</t> | </li> | |||
<t> | <li> | |||
The point of contact, including an email address. The point of | The point of contact, including an email address. The point of | |||
contact can consume up to 256 bytes (or more if IANA permits). | contact can consume up to 256 bytes (or more if IANA permits). | |||
For assignments made on a Standards Action basis, the point of | For assignments made on a Standards Action basis, the point of | |||
contact is always IESG. | contact is always IESG. | |||
</t> | </li> | |||
</ol> | ||||
</list> | <section numbered="true" toc="default"> | |||
</t> | <name>Initial Registry</name> | |||
<t> | ||||
<section title="Initial Registry"> | The initial registry is in <xref target="varlist" format="default"/>. | |||
<t> | </t> | |||
The initial registry is in <xref target="varlist"/>. | <table anchor="varlist" align="center"> | |||
</t> | <name>Initial List of Path Variables</name> | |||
<thead> | ||||
<texttable title="Initial List of Path Variables" anchor='varlist'> | <tr> | |||
<th align="left">Variable Name</th> | ||||
<ttcol>Variable Name</ttcol> | <th align="left">RFC</th> | |||
<ttcol>RFC</ttcol> | <th align="left">Point of Contact</th> | |||
<ttcol>Point of Contact</ttcol> | </tr> | |||
</thead> | ||||
<c>${ietf.org:CPU_ARCH}</c> <c>RFC 5661</c> <c>IESG</c> | <tbody> | |||
<c>${ietf.org:OS_TYPE}</c> <c>RFC 5661</c> <c>IESG</c> | <tr> | |||
<c>${ietf.org:OS_VERSION}</c> <c>RFC 5661</c> <c>IESG</c> | <td align="left">${ietf.org:CPU_ARCH}</td> | |||
<td align="left">RFC 8881</td> | ||||
</texttable> | <td align="left">IESG</td> | |||
</tr> | ||||
<t> | <tr> | |||
<td align="left">${ietf.org:OS_TYPE}</td> | ||||
<td align="left">RFC 8881</td> | ||||
<td align="left">IESG</td> | ||||
</tr> | ||||
<tr> | ||||
<td align="left">${ietf.org:OS_VERSION}</td> | ||||
<td align="left">RFC 8881</td> | ||||
<td align="left">IESG</td> | ||||
</tr> | ||||
</tbody> | ||||
</table> | ||||
<t> | ||||
IANA has created registries for the values | IANA has created registries for the values | |||
of the variable names ${ietf.org:CPU_ARCH} and | of the variable names ${ietf.org:CPU_ARCH} and | |||
${ietf.org:OS_TYPE}. See Sections <xref target="cpu_arch" | ${ietf.org:OS_TYPE}. See Sections <xref target="cpu_arch" format="counter | |||
format="counter" /> | "/> | |||
and <xref target="os_type" format="counter" />. | and <xref target="os_type" format="counter"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
For the values of the variable | For the values of the variable | |||
${ietf.org:OS_VERSION}, no registry is needed as | ${ietf.org:OS_VERSION}, no registry is needed as | |||
the specifics of the values of the variable will | the specifics of the values of the variable will | |||
vary with the value of ${ietf.org:OS_TYPE}. Thus, | vary with the value of ${ietf.org:OS_TYPE}. Thus, | |||
values for ${ietf.org:OS_VERSION} are on a | values for ${ietf.org:OS_VERSION} are on a | |||
Hierarchical Allocation basis and are of no concern | Hierarchical Allocation basis and are of no concern | |||
to IANA. | to IANA. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="Updating Registrations"> | <name>Updating Registrations</name> | |||
<t> | <t> | |||
The update of an assignment made on a Standards Action basis | The update of an assignment made on a Standards Action basis | |||
will require IESG Approval on the advice of a Designated Expert. | will require IESG Approval on the advice of a Designated Expert. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
The registrant can always update the point of contact of an assignment | The registrant can always update the point of contact of an assignment | |||
made on a First Come First Serve basis. Any other update will require | made on a First Come First Serve basis. Any other update will require | |||
Expert Review. | Expert Review. | |||
</t> | </t> | |||
</section> | ||||
</section> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="cpu_arch" numbered="true" toc="default"> | |||
<section title="Values for the ${ietf.org:CPU_ARCH} Variable" anchor="cpu_arch | <name>Values for the ${ietf.org:CPU_ARCH} Variable</name> | |||
"> | <t> | |||
<t> | ||||
IANA created a registry called the "NFSv4 ${ietf.org:CPU_ARCH} Value Regist ry". | IANA created a registry called the "NFSv4 ${ietf.org:CPU_ARCH} Value Regist ry". | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
Assignments to the registry are made on a First Come First Serve | Assignments to the registry are made on a First Come First Serve | |||
basis. The zero-length value of ${ietf.org:CPU_ARCH} is Reserved. | basis. The zero-length value of ${ietf.org:CPU_ARCH} is Reserved. | |||
Values with a prefix of "PRIV" are designated for Private Use. | Values with a prefix of "PRIV" are designated for Private Use. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
The registry is a list of assignments, each | The registry is a list of assignments, each | |||
containing three fields. | containing three fields. | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
A value of the ${ietf.org:CPU_ARCH} variable. The value | A value of the ${ietf.org:CPU_ARCH} variable. The value | |||
must be 1 to 32 UTF-8 characters long. The value must be unique. | must be 1 to 32 UTF-8 characters long. The value must be unique. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
An explanation (consuming no more than 1024 | An explanation (consuming no more than 1024 | |||
bytes, or more if IANA permits) of what CPU | bytes, or more if IANA permits) of what CPU | |||
architecture the value denotes. A reference to | architecture the value denotes. A reference to | |||
the explanation can be substituted. | the explanation can be substituted. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
The point of contact, including an email address. The point of | The point of contact, including an email address. The point of | |||
contact can consume up to 256 bytes (or more if IANA permits). | contact can consume up to 256 bytes (or more if IANA permits). | |||
</t> | </li> | |||
</ol> | ||||
</list> | <section numbered="true" toc="default"> | |||
</t> | <name>Initial Registry</name> | |||
<t> | ||||
<section title="Initial Registry"> | ||||
<t> | ||||
There is no initial registry. | There is no initial registry. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="Updating Registrations"> | <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 anchor="os_type" numbered="true" toc="default"> | |||
<section title="Values for the ${ietf.org:OS_TYPE} Variable" anchor="os_type"> | <name>Values for the ${ietf.org:OS_TYPE} Variable</name> | |||
<t> | <t> | |||
IANA created a registry called the "NFSv4 ${ietf.org:OS_TYPE} Value Registr y". | IANA created a registry called the "NFSv4 ${ietf.org:OS_TYPE} Value Registr y". | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
Assignments to the registry are made on a First Come First Serve | Assignments to the registry are made on a First Come First Serve | |||
basis. The zero-length value of ${ietf.org:OS_TYPE} is Reserved. | basis. The zero-length value of ${ietf.org:OS_TYPE} is Reserved. | |||
Values with a prefix of "PRIV" are designated for Private Use. | Values with a prefix of "PRIV" are designated for Private Use. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
The registry is a list of assignments, each | The registry is a list of assignments, each | |||
containing three fields. | containing three fields. | |||
<list style='numbers'> | </t> | |||
<t> | <ol spacing="normal" type="1"> | |||
<li> | ||||
A value of the ${ietf.org:OS_TYPE} variable. The value | A value of the ${ietf.org:OS_TYPE} variable. The value | |||
must be 1 to 32 UTF-8 characters long. The value must be unique. | must be 1 to 32 UTF-8 characters long. The value must be unique. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
An explanation (consuming no more than 1024 | An explanation (consuming no more than 1024 | |||
bytes, or more if IANA permits) of what CPU | bytes, or more if IANA permits) of what CPU | |||
architecture the value denotes. A reference to | architecture the value denotes. A reference to | |||
the explanation can be substituted. | the explanation can be substituted. | |||
</t> | </li> | |||
<li> | ||||
<t> | ||||
The point of contact, including an email address. The point of | The point of contact, including an email address. The point of | |||
contact can consume up to 256 bytes (or more if IANA permits). | contact can consume up to 256 bytes (or more if IANA permits). | |||
</t> | </li> | |||
</ol> | ||||
</list> | <section numbered="true" toc="default"> | |||
</t> | <name>Initial Registry</name> | |||
<t> | ||||
<section title="Initial Registry"> | ||||
<t> | ||||
There is no initial registry. | There is no initial registry. | |||
</t> | </t> | |||
</section> | </section> | |||
<section numbered="true" toc="default"> | ||||
<section title="Updating Registrations"> | <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> | ||||
<!-- $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 | <references> | |||
$ --> | <name>References</name> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <references> | |||
<!-- Copyright (C) The Internet Society (2006) --> | <name>Normative References</name> | |||
<references title="Normative References"> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<reference anchor='RFC2119'> | FC.2119.xml"/> | |||
<front> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<title abbrev='RFC Key Words'>Key words for use in RFCs to Indicate Requi | FC.4506.xml"/> | |||
rement Levels</title> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<author initials='S.' surname='Bradner' fullname='Scott Bradner'> | FC.5531.xml"/> | |||
<organization>Harvard University</organization> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<address> | FC.2203.xml"/> | |||
<postal> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<street>1350 Mass. Ave.</street> | FC.4121.xml"/> | |||
<street>Cambridge</street> | ||||
<street>MA 02138</street></postal> | ||||
<phone>- +1 617 495 3864</phone> | ||||
<email>sob@harvard.edu</email></address></author> | ||||
<date year='1997' month='March' /> | ||||
</front> | ||||
<seriesInfo name='BCP' value='14' /> | ||||
<seriesInfo name='RFC' value='2119' /> | ||||
<format type='TXT' target='http://www.rfc-editor.org/rfc/rfc2119.txt' /> | ||||
</reference> | ||||
<reference anchor='RFC4506'> | ||||
<front> | ||||
<title>XDR: External Data Representation Standard</title> | ||||
<author initials='M.' surname='Eisler' fullname='M. Eisler' role='editor'> | ||||
<organization /></author> | ||||
<date year='2006' month='May' /> | ||||
<abstract> | ||||
<t><p>This document describes the External Data | ||||
Representation Standard (XDR) protocol as it is currently | ||||
deployed and accepted. This document obsoletes RFC | ||||
1832. [STANDARDS TRACK]</p></t></abstract></front> | ||||
<seriesInfo name='STD' value='67' /> | ||||
<seriesInfo name='RFC' value='4506' /> | ||||
<format type='TXT' octets='55477' target='http://www.rfc-editor.org/rfc/rf | ||||
c4506.txt' /> | ||||
</reference> | ||||
<reference anchor='RFC5531'> | ||||
<front> | ||||
<title> | ||||
RPC: Remote Procedure Call Protocol Specification Version 2 | ||||
</title> | ||||
<author initials='R.' surname='Thurlow' fullname='R. Thurlow'> | ||||
<organization /> | ||||
</author> | ||||
<date year='2009' month='May' /> | ||||
<abstract> | ||||
<t>This document describes the Open Network Computing (ONC) Remote | ||||
Procedure Call (RPC) version 2 protocol as it is currently deployed | ||||
and accepted. This document obsoletes RFC 1831. [STANDARDS | ||||
TRACK]</t></abstract></front> | ||||
<seriesInfo name='RFC' value='5531' /> | ||||
<format type='TXT' octets='161720' | ||||
target='ftp://ftp.isi.edu/in-notes/rfc5531.txt' /> | ||||
</reference> | ||||
<reference anchor='RFC2203'> | ||||
<front> | ||||
<title>RPCSEC_GSS Protocol Specification</title> | ||||
<author initials='M.' surname='Eisler' fullname='Michael Eisler'> | ||||
<organization>Sun Microsystems, Inc.</organization> | ||||
<address> | ||||
<postal> | ||||
<street>M/S UCOS03</street> | ||||
<street>2550 Garcia Avenue</street> | ||||
<street>Mountain View</street> | ||||
<street>CA 94043</street></postal> | ||||
<phone>+1 (719) 599-9026</phone> | ||||
<email>mre@eng.sun.com</email></address></author> | ||||
<author initials='A.' surname='Chiu' fullname='Alex Chiu'> | ||||
<organization>Sun Microsystems, Inc.</organization> | ||||
<address> | ||||
<postal> | ||||
<street>M/S UMPK17-203</street> | ||||
<street>2550 Garcia Avenue</street> | ||||
<street>Mountain View</street> | ||||
<street>CA 94043</street></postal> | ||||
<phone>+1 (415) 786-6465</phone> | ||||
<email>hacker@eng.sun.com</email></address></author> | ||||
<author initials='L.' surname='Ling' fullname='Lin Ling'> | ||||
<organization>Sun Microsystems, Inc.</organization> | ||||
<address> | ||||
<postal> | ||||
<street>M/S UMPK17-201</street> | ||||
<street>2550 Garcia Avenue</street> | ||||
<street>Mountain View</street> | ||||
<street>CA 94043</street></postal> | ||||
<phone>+1 (415) 786-5084</phone> | ||||
<email>lling@eng.sun.com</email></address></author> | ||||
<date year='1997' month='September' /> | ||||
<area>Security</area> | ||||
<keyword>generic security service</keyword> | ||||
<keyword>remote procedure call</keyword> | ||||
<keyword>security</keyword> | ||||
<abstract> | ||||
<t> | ||||
This memo describes an ONC/RPC security flavor that allows RPC | ||||
protocols to access the Generic Security Services Application | ||||
Programming Interface (referred to henceforth as GSS-API). | ||||
</t></abstract></front> | ||||
<seriesInfo name='RFC' value='2203' /> | ||||
<format type='TXT' octets='50937' target='http://www.rfc-editor.org/rfc/rf | ||||
c2203.txt' /> | ||||
<format type='HTML' octets='64234' target='http://xml.resource.org/public/ | ||||
rfc/html/rfc2203.html' /> | ||||
<format type='XML' octets='50069' target='http://xml.resource.org/public/r | ||||
fc/xml/rfc2203.xml' /> | ||||
</reference> | ||||
<reference anchor='RFC4121'> | ||||
<front> | ||||
<title>The Kerberos Version 5 Generic Security Service Application Progr | ||||
am Interface (GSS-API) Mechanism Version 2</title> | ||||
<author initials='L.' surname='Zhu'> | ||||
<organization>Microsoft</organization> | ||||
</author> | ||||
<author initials='K.' surname='Jaganathan'> | ||||
<organization>Microsoft</organization> | ||||
</author> | ||||
<author initials='S.' surname='Hartman'> | ||||
<organization>MIT</organization> | ||||
</author> | ||||
<date year='2005' month='July' /> | ||||
<abstract> | ||||
<t> | ||||
RFC 1964 is updated and incremental changes are proposed in | ||||
response to recent developments such as the introduction of | ||||
Kerberos crypto-system framework. These changes support the | ||||
inclusion of new crypto-systems, by defining new per-message | ||||
tokens along with their encryption and checksum algorithms | ||||
based on the crypto-system profiles. | ||||
</t> | ||||
</abstract> | ||||
</front> | ||||
<seriesInfo name='RFC' value='4121' /> | ||||
<format type='TXT' target='http://www.rfc-editor.org/rfc/rfc4121.txt' /> | ||||
</reference> | ||||
<reference anchor="hardlink"> | ||||
<front> | ||||
<title abbrev="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 </title> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<reference anchor='RFC2743'> | ||||
<front> | ||||
<title abbrev='GSS-API'>Generic Security Service Application | ||||
Program Interface Version 2, Update 1</title> | ||||
<author initials='J.' surname='Linn' fullname='John Linn'> | ||||
<organization>RSA Laboratories</organization> | ||||
<address> | ||||
<postal> | ||||
<street>20 Crosby Drive</street> | ||||
<city>Bedford</city> | ||||
<region>MA</region> | ||||
<code>01730</code> | ||||
<country>US</country></postal> | ||||
<phone>+1 781 687 7817</phone> | ||||
<email>jlinn@rsasecurity.com</email></address></author> | ||||
<date year='2000' month='January' /> | ||||
<abstract> | ||||
<t>The Generic Security Service Application Program | ||||
Interface (GSS-API), Version 2, as defined in, provides | ||||
security services to callers in a generic fashion, | ||||
supportable with a range of underlying mechanisms and | ||||
technologies and hence allowing source-level portability of | ||||
applications to different environments. This specification | ||||
defines GSS-API services and primitives at a level | ||||
independent of underlying mechanism and programming language | ||||
environment, and is to be complemented by other, related | ||||
specifications:</t> | ||||
<t>documents defining specific parameter bindings for | ||||
particular language environments</t> | ||||
<t>documents defining token formats, protocols, and | ||||
procedures to be implemented in order to realize GSS-API | ||||
services atop particular security mechanisms</t> <t>This | ||||
memo obsoletesmaking specific, incremental changes in | ||||
response to implementation experience and liaison | ||||
requests. It is intended, therefore, that this memo or a | ||||
successor version thereto will become the basis for | ||||
subsequent progression of the GSS-API specification on the | ||||
standards track.</t></abstract></front> | ||||
<seriesInfo name='RFC' value='2743' /> | ||||
<format type='TXT' octets='229418' | ||||
target='http://www.rfc-editor.org/rfc/rfc2743.txt' /> | ||||
</reference> | ||||
<reference anchor='RDMAP'> | ||||
<front> | ||||
<title abbrev='RDMAP - WIP'>A Remote Direct Memory Access Protocol | ||||
Specification | ||||
</title> | ||||
<author initials='R.' surname='Recio'> | ||||
<organization>IBM Corporation</organization> | ||||
</author> | ||||
<author initials='B.' surname='Metzler'> | ||||
<organization>IBM Corporation</organization> | ||||
</author> | ||||
<author initials='P.' surname='Culley'> | ||||
<organization>Hewlett-Packard Company</organization> | ||||
</author> | ||||
<author initials='J.' surname='Hilland'> | ||||
<organization>Hewlett-Packard Company</organization> | ||||
</author> | ||||
<author initials='D.' surname='Garcia'> | ||||
<organization></organization> | ||||
</author> | ||||
<date year='2007' month='October' /> | ||||
<abstract> | ||||
<t> | ||||
This document defines a Remote Direct Memory Access Protocol | ||||
(RDMAP) that operates over the Direct Data Placement Protocol (DDP | ||||
protocol). RDMAP provides read and write services directly to | ||||
applications and enables data to be transferred directly into | ||||
Upper Layer Protocol (ULP) buffers without intermediate data | ||||
copies. It also enables a kernel bypass implementation. | ||||
</t></abstract></front> | ||||
<seriesInfo name='RFC' value='5040' /> | ||||
<format type='TXT' target='http://www.rfc-editor.org/rfc/rfc5040.txt' /> | ||||
</reference> | ||||
<reference anchor='RFC5403'> | ||||
<front> | ||||
<title>RPCSEC_GSS Version 2</title> | ||||
<author initials='M.' surname='Eisler' fullname='M. Eisler'> | ||||
<organization /></author> | ||||
<date year='2009' month='February' /> | ||||
<abstract> | ||||
<t>This document describes version 2 of the RPCSEC_GSS protocol. Version | ||||
2 is the same as version 1 (specified in RFC 2203) except that support for chan | ||||
nel bindings has been added. RPCSEC_GSS allows remote procedure call (RPC) prot | ||||
ocols to access the Generic Security Services Application Programming Interface | ||||
(GSS-API). [STANDARDS TRACK]</t></abstract></front> | ||||
<seriesInfo name='RFC' value='5403' /> | ||||
<format type='TXT' octets='30812' target='ftp://ftp.isi.edu/in-notes/rfc5 | ||||
403.txt' /> | ||||
</reference> | ||||
<reference anchor='RFC5662'> | ||||
<front> | ||||
<title> | ||||
Network File System (NFS) Version 4 Minor Version 1 External Data | ||||
Representation Standard (XDR) Description | ||||
</title> | ||||
<author initials='S' surname='Shepler' fullname='Spencer Shepler' role='editor'> | ||||
<organization /> | ||||
</author> | ||||
<author initials='M' surname='Eisler' fullname='Mike Eisler' role='editor'> | ||||
<organization /> | ||||
</author> | ||||
<author initials='D' surname='Noveck' fullname='David Noveck' role='editor'> | ||||
<organization /> | ||||
</author> | ||||
<date month='January' year='2010' /> | ||||
<abstract><t>This Internet-Draft provides the XDR description for NFSv4 minor ve | ||||
rsion one.</t></abstract> | ||||
</front> | ||||
<seriesInfo name='RFC' value='5662' /> | ||||
</reference> | ||||
<reference anchor="symlink"> | ||||
<front> | ||||
<title>Section 3.372 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 </title> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<reference anchor='RFC5665'> | ||||
<front> | ||||
<title> | ||||
IANA Considerations for Remote Procedure Call (RPC) Network | ||||
Identifiers and Universal Address Formats | ||||
</title> | ||||
<author initials='M' surname='Eisler' fullname='Mike Eisler'> | ||||
<organization /> | ||||
</author> | ||||
<date month='January' year='2010' /> | ||||
<abstract> | ||||
<t> | ||||
IANA Considerations for RPC Net Identifiers and Universal Address Formats. | ||||
</t> | ||||
</abstract> | ||||
</front> | ||||
<seriesInfo name='RFC' value='5665' /> | ||||
</reference> | ||||
<reference anchor="read_atime"> | ||||
<front> | ||||
<title>Section 'read()' of System Interfaces of | ||||
The Open Group Base Specifications Issue 6 | ||||
IEEE Std 1003.1, 2004 Edition, HTML Version (www.opengroup.org), ISBN | ||||
1931624232 </title> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<reference anchor="readdir_atime"> | ||||
<front> | ||||
<title>Section 'readdir()' of System Interfaces of | ||||
The Open Group Base Specifications Issue 6 | ||||
IEEE Std 1003.1, 2004 Edition, HTML Version (www.opengroup.org), ISBN | ||||
1931624232 </title> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<reference anchor="write_atime"> | ||||
<front> | ||||
<title>Section 'write()' of System Interfaces of | ||||
The Open Group Base Specifications Issue 6 | ||||
IEEE Std 1003.1, 2004 Edition, HTML Version (www.opengroup.org), ISBN | ||||
1931624232 </title> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<reference anchor='RFC3454'> | ||||
<front> | ||||
<title>Preparation of Internationalized Strings ("stringprep")</title> | ||||
<author initials='P.' surname='Hoffman' fullname='P. Hoffman'> | ||||
<organization /></author> | ||||
<author initials='M.' surname='Blanchet' fullname='M. Blanchet'> | ||||
<organization /></author> | ||||
<date year='2002' month='December' /> | ||||
<abstract> | ||||
<t> | ||||
<p>This document describes a framework for preparing | ||||
Unicode text strings in order to increase the likelihood | ||||
that string input and string comparison work in ways that | ||||
make sense for typical users throughout the world. The | ||||
stringprep protocol is useful for protocol identifier | ||||
values, company and personal names, internationalized | ||||
domain names, and other text strings. This document does | ||||
not specify how protocols should prepare text | ||||
strings. Protocols must create profiles of stringprep in | ||||
order to fully specify the processing options. [STANDARDS | ||||
TRACK] </p> | ||||
</t> | ||||
</abstract> | ||||
</front> | ||||
<seriesInfo name='RFC' value='3454' /> | ||||
<format type='TXT' octets='138684' target='http://www.rfc-editor.org/rfc/r | ||||
fc3454.txt' /> | ||||
</reference> | ||||
<reference anchor="chmod"> | ||||
<front> | ||||
<title>Section 'chmod()' of System Interfaces of | ||||
The Open Group Base Specifications Issue 6 | ||||
IEEE Std 1003.1, 2004 Edition, HTML Version (www.opengroup.org), ISBN | ||||
1931624232 </title> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<reference anchor="ISO.10646-1.1993"> | ||||
<front> | ||||
<title>Information Technology - Universal Multiple-octet coded | ||||
Character Set (UCS) - Part 1: Architecture and Basic Multilingual | ||||
Plane</title> | ||||
<author> | ||||
<organization>International Organization for Standardization | ||||
</organization> | ||||
</author> | ||||
<date month="May" year="1993" /> | ||||
</front> | ||||
<seriesInfo name="ISO" value="Standard 10646-1" /> | ||||
</reference> | ||||
<reference anchor='RFC2277'> | ||||
<front> | ||||
<title abbrev='Charset Policy'> | ||||
IETF Policy on Character Sets and Languages</title> | ||||
<author initials='H.' surname='Alvestrand' | ||||
fullname='Harald Tveit Alvestrand'> | ||||
<organization>UNINETT</organization> | ||||
<address> | ||||
<postal> | ||||
<street>P.O.Box 6883 Elgeseter</street> | ||||
<street>N-7002 TRONDHEIM</street> | ||||
<country>NORWAY</country></postal> | ||||
<phone>+47 73 59 70 94</phone> | ||||
<email>Harald.T.Alvestrand@uninett.no</email></address></author> | ||||
<date year='1998' month='January' /> | ||||
<area>Applications</area> | ||||
<keyword>Internet Engineering Task Force</keyword> | ||||
<keyword>character encoding</keyword></front> | ||||
<seriesInfo name='BCP' value='18' /> | ||||
<seriesInfo name='RFC' value='2277' /> | ||||
<format type='TXT' octets='16622' | ||||
target='http://www.rfc-editor.org/rfc/rfc2277.txt' /> | ||||
<format type='HTML' octets='26556' | ||||
target='http://xml.resource.org/public/rfc/html/rfc2277.html' /> | ||||
<format type='XML' octets='15544' | ||||
target='http://xml.resource.org/public/rfc/xml/rfc2277.xml' /> | ||||
</reference> | ||||
<reference anchor='RFC3491'> | ||||
<front> | ||||
<title>Nameprep: A Stringprep Profile for Internationalized Domain Names | ||||
(IDN)</title> | ||||
<author initials='P.' surname='Hoffman' fullname='P. Hoffman'> | ||||
<organization /></author> | ||||
<author initials='M.' surname='Blanchet' fullname='M. Blanchet'> | ||||
<organization /></author> | ||||
<date year='2003' month='March' /> | ||||
<abstract> | ||||
<t> | ||||
<p>This document describes how to prepare | ||||
internationalized domain name (IDN) labels in order to | ||||
increase the likelihood that name input and name | ||||
comparison work in ways that make sense for typical users | ||||
throughout the world. This profile of the stringprep | ||||
protocol is used as part of a suite of on-the-wire | ||||
protocols for internationalizing the Domain Name System | ||||
(DNS). [STANDARDS TRACK] </p> | ||||
</t> | ||||
</abstract> | ||||
</front> | ||||
<seriesInfo name='RFC' value='3491' /> | ||||
<format type='TXT' octets='10316' target='http://www.rfc-editor.org/rfc/rf | ||||
c3491.txt' /> | ||||
</reference> | ||||
<reference anchor="fcntl"> | ||||
<front> | ||||
<title>Section 'fcntl()' of System Interfaces of | ||||
The Open Group Base Specifications Issue 6 | ||||
IEEE Std 1003.1, 2004 Edition, HTML Version (www.opengroup.org), ISBN | ||||
1931624232 </title> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<reference anchor="fsync"> | ||||
<front> | ||||
<title>Section 'fsync()' of System Interfaces of | ||||
The Open Group Base Specifications Issue 6 | ||||
IEEE Std 1003.1, 2004 Edition, HTML Version (www.opengroup.org), ISBN | ||||
1931624232 </title> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<reference anchor="passwd"> | ||||
<front> | ||||
<title>Section 'getpwnam()' of System Interfaces of | ||||
The Open Group Base Specifications Issue 6 | ||||
IEEE Std 1003.1, 2004 Edition, HTML Version (www.opengroup.org), ISBN | ||||
1931624232 </title> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<reference anchor="unlink"> | ||||
<front> | ||||
<title>Section 'unlink()' of System Interfaces of | ||||
The Open Group Base Specifications Issue 6 | ||||
IEEE Std 1003.1, 2004 Edition, HTML Version (www.opengroup.org), ISBN | ||||
1931624232 </title> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<!-- 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/rfc18 | ||||
31.txt' /> | ||||
</reference> --> | ||||
<reference anchor='RFC4055'> | ||||
<front> | <reference anchor="hardlink" target="https://www.opengroup.org"> | |||
<title> | <front> | |||
Additional Algorithms and Identifiers for RSA Cryptography for use in | <title abbrev="Open Group">Section 3.191 of Chapter 3 of | |||
the Internet X.509 Public Key Infrastructure Certificate and | Base Definitions of The Open Group Base Specifications Issue 6 | |||
Certificate Revocation List (CRL) Profile | IEEE Std 1003.1, 2004 Edition, HTML Version </title> | |||
</title> | <seriesInfo name="ISBN" value="1931624232"/> | |||
<author initials='J.' surname='Schaad' fullname='J. Schaad'> | <author> | |||
<organization /></author> | <organization>The Open Group </organization> | |||
<author initials='B.' surname='Kaliski' fullname='B. Kaliski'> | </author> | |||
<organization /></author> | <date year="2004"/> | |||
<author initials='R.' surname='Housley' fullname='R. Housley'> | </front> | |||
<organization /></author> | </reference> | |||
<date year='2005' month='June' /> | ||||
<abstract> | ||||
<t><p>This document supplements RFC 3279. It describes the | ||||
conventions for using the RSA Probabilistic Signature Scheme | ||||
(RSASSA-PSS) signature algorithm, the RSA Encryption Scheme - | ||||
Optimal Asymmetric Encryption Padding (RSAES-OAEP) key transport | ||||
algorithm and additional one-way hash functions with the | ||||
Public-Key Cryptography Standards (PKCS) #1 version 1.5 signature | ||||
algorithm in the Internet X.509 Public Key Infrastructure | ||||
(PKI). Encoding formats, algorithm identifiers, and parameter | ||||
formats are specified. [STANDARDS | ||||
TRACK]</p> | ||||
</t> | ||||
</abstract> | ||||
</front> | ||||
<seriesInfo name='RFC' value='4055' /> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<format type='TXT' octets='57479' target='http://www.rfc-editor.org/rfc/rfc4 | FC.2743.xml"/> | |||
055.txt' /> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
</reference> | FC.5040.xml"/> | |||
<reference anchor="CSOR_AES"> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<front> | FC.5403.xml"/> | |||
<title>Cryptographic Algorithm Object Registration | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
</title> | FC.5662.xml"/> | |||
<author> | ||||
<organization>National Institute of Standards and Technology | ||||
</organization> | ||||
</author> | ||||
<date month="November" year="2007" /> | ||||
</front> | ||||
<seriesInfo name="URL" value="http://csrc.nist.gov/groups/ST/crypto_apps_i | ||||
nfra/csor/algorithms.html" /> | ||||
</reference> | ||||
<?rfc include="reference.RFC.7861.xml"?> | ||||
<?rfc include="reference.RFC.4120.xml"?> | ||||
<?rfc include="reference.RFC.4033.xml"?> | ||||
<?rfc include="reference.RFC.7858.xml"?> | ||||
<?rfc include="reference.RFC.8000.xml"?> | ||||
<?rfc include="reference.RFC.8166.xml"?> | ||||
<?rfc include="reference.RFC.8267.xml"?> | ||||
<?rfc include="reference.RFC.8484.xml"?> | ||||
</references> | ||||
<references title="Informative References"> | <reference anchor="symlink" target="https://www.opengroup.org"> | |||
<?rfc include="reference.I-D.roach-bis-documents.xml"?> | <front> | |||
<reference anchor='RFC3530'> | <title>Section 3.372 of Chapter 3 of | |||
<front> | Base Definitions of The Open Group Base Specifications Issue 6 | |||
<title>Network File System (NFS) version 4 Protocol</title> | IEEE Std 1003.1, 2004 Edition, HTML Version </title> | |||
<author initials="S." surname="Shepler" fullname="S. Shepler"> | <seriesInfo name="ISBN" value="1931624232"/> | |||
<organization>Sun Microsystems, Inc.</organization> | <author> | |||
</author> | <organization>The Open Group </organization> | |||
<author initials="B." surname="Callaghan" fullname="B. Callaghan"> | </author> | |||
<organization>Sun Microsystems, Inc.</organization> | <date year="2004"/> | |||
</author> | </front> | |||
<author initials="D." surname="Robinson" fullname="D. Robinson"> | </reference> | |||
<organization>Sun Microsystems, Inc.</organization> | ||||
</author> | ||||
<author initials="R." surname="Thurlow" fullname="R. Thurlow"> | ||||
<organization>Sun Microsystems, Inc.</organization> | ||||
</author> | ||||
<author initials="C." surname="Beame" fullname="C. Beame"> | ||||
<organization>Hummingbird, Ltd.</organization> | ||||
</author> | ||||
<author initials="M." surname="Eisler" fullname="M. Eisler"> | ||||
<organization>NetApp</organization> | ||||
</author> | ||||
<author initials="D." surname="Noveck" fullname="D. Noveck"> | ||||
<organization>NetApp</organization> | ||||
</author> | ||||
<date year="2003" month="April"/> | ||||
</front> | ||||
<seriesInfo name="RFC" value="3530"/> | ||||
<format type="TXT" octets="600988" | ||||
target="http://www.rfc-editor.org/rfc/rfc3530.txt"/> | ||||
</reference> | ||||
<reference anchor='RFC1813'> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R FC.5665.xml"/> | |||
<front> | <reference anchor="read_atime" target="https://www.opengroup.org"> | |||
<title abbrev='NFSv3 Protocol'>NFS Version 3 Protocol Specification</title> | <front> | |||
<author initials='B.' surname='Callaghan' fullname='Brent Callaghan'> | <title>Section 'read()' of | |||
<organization>Sun Microsystems, Inc.</organization> | System Interfaces of The Open Group Base Specifications Issue 6 | |||
<address> | IEEE Std 1003.1, 2004 Edition, HTML Version </title> | |||
<postal> | <seriesInfo name="ISBN" value="1931624232"/> | |||
<street>2550 Garcia Avenue</street> | <author> | |||
<street>Mailstop UMTV05-44</street> | <organization>The Open Group </organization> | |||
<city>Mountain View</city> | </author> | |||
<region>CA</region> | <date year="2004"/> | |||
<code>94043-1100</code> | </front> | |||
<country>US</country></postal> | </reference> | |||
<phone>+1 415 336 1051</phone> | ||||
<facsimile>+1 415 336 6015</facsimile> | ||||
<email>brent.callaghan@eng.sun.com</email></address></author> | ||||
<author initials='B.' surname='Pawlowski' fullname='Brian Pawlowski'> | <reference anchor="readdir_atime" target="https://www.opengroup.org"> | |||
<organization>NetApp</organization> | <front> | |||
<address> | <title>Section 'readdir()' of | |||
<postal> | System Interfaces of The Open Group Base Specifications Issue 6 | |||
<street>319 North Bernardo Ave.</street> | IEEE Std 1003.1, 2004 Edition, HTML Version </title> | |||
<city>Mountain View</city> | <seriesInfo name="ISBN" value="1931624232"/> | |||
<region>CA</region> | <author> | |||
<code>94043</code> | <organization>The Open Group </organization> | |||
<country>US</country></postal> | </author> | |||
<phone>+1 415 428 5136</phone> | <date year="2004"/> | |||
<facsimile>+1 415 428 5151</facsimile> | </front> | |||
<email>beepy@netapp.com</email></address></author> | </reference> | |||
<author initials='P.' surname='Staubach' fullname='Peter Staubach'> | <reference anchor="write_atime" target="https://www.opengroup.org"> | |||
<organization>Sun Microsystems, Inc.</organization> | <front> | |||
<address> | <title>Section 'write()' of | |||
<postal> | System Interfaces of The Open Group Base Specifications Issue 6 | |||
<street>2550 Garcia Avenue</street> | IEEE Std 1003.1, 2004 Edition, HTML Version </title> | |||
<street>Mailstop UMTV05-44</street> | <seriesInfo name="ISBN" value="1931624232"/> | |||
<city>Mountain View</city> | <author> | |||
<region>CA</region> | <organization>The Open Group </organization> | |||
<code>94043-1100</code> | </author> | |||
<country>US</country></postal> | <date year="2004"/> | |||
<phone>+1 415 336 5615</phone> | </front> | |||
<facsimile>+1 415 336 6015</facsimile> | </reference> | |||
<email>peter.staubach@eng.sun.com</email></address></author> | ||||
<date year='1995' month='June' /> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<abstract> | FC.3454.xml"/> | |||
<t>This paper describes the NFSv3 protocol. This paper is provided so that peop | ||||
le can write compatible implementations.</t></abstract></front> | ||||
<seriesInfo name='RFC' value='1813' /> | <reference anchor="chmod" target="https://www.opengroup.org"> | |||
<format type='TXT' octets='229793' target='http://www.rfc-editor.org/rfc/rfc1813 | <front> | |||
.txt' /> | <title>Section 'chmod()' of | |||
</reference> | System Interfaces of The Open Group Base Specifications Issue 6 | |||
IEEE Std 1003.1, 2004 Edition, HTML Version </title> | ||||
<seriesInfo name="ISBN" value="1931624232"/> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<reference anchor='RFC2847'> | <reference anchor="ISO.10646-1.1993"> | |||
<front> | ||||
<title>Information Technology - | ||||
Universal Multiple-octet coded Character Set (UCS) - | ||||
Part 1: Architecture and Basic Multilingual Plane </title> | ||||
<seriesInfo name="ISO" value="Standard 10646-1"/> | ||||
<author> | ||||
<organization>International Organization for Standardization | ||||
</organization> | ||||
</author> | ||||
<date month="May" year="1993"/> | ||||
</front> | ||||
</reference> | ||||
<front> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<title>LIPKEY - A Low Infrastructure Public Key Mechanism Using SPKM</titl | FC.2277.xml"/> | |||
e> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<author initials='M.' surname='Eisler' fullname='M. Eisler'> | FC.3491.xml"/> | |||
<organization /></author> | ||||
<date year='2000' month='June' /> | ||||
<abstract> | <reference anchor="fcntl" target="https://www.opengroup.org"> | |||
<t><p>This memorandum describes a method whereby one can | <front> | |||
use GSS-API (Generic Security Service Application Program | <title>Section 'fcntl()' of | |||
Interface) to supply a secure channel between a client and | System Interfaces of The Open Group Base Specifications Issue 6 | |||
server, authenticating the client with a password, and a | IEEE Std 1003.1, 2004 Edition, HTML Version </title> | |||
server with a public key certificate. [STANDARDS TRACK] | <seriesInfo name="ISBN" value="1931624232"/> | |||
</p></t> | <author> | |||
</abstract> | <organization>The Open Group </organization> | |||
</front> | </author> | |||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<seriesInfo name='RFC' value='2847' /> | <reference anchor="fsync" target="https://www.opengroup.org"> | |||
<format type='TXT' octets='50045' target='http://www.rfc-editor.org/rfc/rf | <front> | |||
c2847.txt' /> | <title>Section 'fsync()' of | |||
</reference> | System Interfaces of The Open Group Base Specifications Issue 6 | |||
IEEE Std 1003.1, 2004 Edition, HTML Version </title> | ||||
<seriesInfo name="ISBN" value="1931624232"/> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<reference anchor='RFC2623'> | <reference anchor="passwd" target="https://www.opengroup.org"> | |||
<front> | ||||
<title>Section 'getpwnam()' of | ||||
System Interfaces of The Open Group Base Specifications Issue 6 | ||||
IEEE Std 1003.1, 2004 Edition, HTML Version </title> | ||||
<seriesInfo name="ISBN" value="1931624232"/> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<front> | <reference anchor="unlink" target="https://www.opengroup.org"> | |||
<title abbrev='NFS Security, RPCSEC_GSS, and Kerberos V5'> | <front> | |||
NFS Version 2 and Version 3 Security Issues and the NFS Protocol's Use | <title>Section 'unlink()' of | |||
of RPCSEC_GSS and Kerberos V5 | System Interfaces of The Open Group Base Specifications Issue 6 | |||
</title> | IEEE Std 1003.1, 2004 Edition, HTML Version </title> | |||
<seriesInfo name="ISBN" value="1931624232"/> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date year="2004"/> | ||||
</front> | ||||
</reference> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4 | ||||
055.xml"/> | ||||
<author initials='M.' surname='Eisler' fullname='Mike Eisler'> | <reference anchor="CSOR_AES" target="https://csrc.nist.gov/projects/computer | |||
<organization>Sun Microsystems, Inc.</organization> | -security-objects-register/algorithm-registration"> | |||
<address> | <front> | |||
<postal> | <title>Computer Security Objects Register | |||
<street>5565 Wilson Road</street> | </title> | |||
<city>Colorado Springs</city> | <author> | |||
<region>CO</region> | <organization>National Institute of Standards and Technology | |||
<code>80919</code> | </organization> | |||
<country>US</country></postal> | </author> | |||
<phone>+1 719 599 9026</phone> | <date month="May" year="2016"/> | |||
<email>mre@eng.sun.com</email></address></author> | </front> | |||
</reference> | ||||
<date year='1999' month='June' /> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
FC.7861.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.4120.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.4033.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.7858.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.8000.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.8166.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.8267.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.8484.xml"/> | ||||
<abstract> | <referencegroup anchor="BCP09" target="https://www.rfc-editor.org/info/bcp | |||
9"> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF | ||||
C.2026.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF | ||||
C.7127.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF | ||||
C.5657.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF | ||||
C.6410.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF | ||||
C.7100.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RF | ||||
C.7475.xml"/> | ||||
</referencegroup> | ||||
<t>This memorandum clarifies various security issues involving | </references> | |||
the NFSv2 and NFSv3 protocols and then | ||||
describes how the NFS protocol | ||||
use the RPCSEC_GSS security flavor protocol and Kerberos V5. | ||||
This memorandum is provided so that people can write compatible | ||||
implementations.</t> | ||||
</abstract> | ||||
</front> | ||||
<seriesInfo name='RFC' value='2623' /> | <references> | |||
<format type='TXT' octets='42521' target='http://www.rfc-editor.org/rfc/rf | <name>Informative References</name> | |||
c2623.txt' /> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml3/reference. | |||
</reference> | I-D.draft-roach-bis-documents-00.xml"/> | |||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.3530.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.1813.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.2847.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.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"> | <organization>Digital Equipment Corporation</organization> | |||
<organization>Digital Equipment Corporation</organization> | </author> | |||
</author> | <date month="June" year="1990"/> | |||
<date month="June" year="1990"/> | <abstract> | |||
<abstract> | <t> | |||
<t> | ||||
Describes reply cache implementation that | Describes reply cache implementation that | |||
avoids work in the server by handling | avoids work in the server by handling | |||
duplicate requests. More important, though | duplicate requests. More important, though | |||
listed as a side-effect, the reply cache | listed as a side-effect, the reply cache | |||
aids in the avoidance of destructive non- | aids in the avoidance of destructive non- | |||
idempotent operation re-application -- | idempotent operation re-application -- | |||
improving correctness. | improving correctness. | |||
</t> | ||||
</abstract> | ||||
</front> | ||||
<refcontent>USENIX Conference Proceedings</refcontent> | ||||
</reference> | ||||
</t> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
</abstract> | FC.3232.xml"/> | |||
</front> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<seriesInfo name="USENIX Conference Proceedings" value="" /> | FC.1833.xml"/> | |||
</reference> | ||||
<reference anchor='RFC3232'> | ||||
<front> | ||||
<title>Assigned Numbers: RFC 1700 is Replaced by an On-line Database</ti | ||||
tle> | ||||
<author initials='J.' surname='Reynolds' | ||||
fullname='J. Reynolds' role='editor'> | ||||
<organization /></author> | ||||
<date year='2002' month='January' /> | ||||
<abstract> | ||||
<t><p>This memo obsoletes RFC 1700 (STD 2) "Assigned | ||||
Numbers", which contained an October 1994 snapshot of assigned | ||||
Internet protocol parameters. This memo provides information | ||||
for the Internet community. </p></t> | ||||
</abstract></front> | ||||
<seriesInfo name='RFC' value='3232' /> | ||||
<format type='TXT' octets='3849' target='http://www.rfc-editor.org/rfc/rfc | ||||
3232.txt' /> | ||||
</reference> | ||||
<reference anchor='RFC1833'> | ||||
<front> | ||||
<title>Binding Protocols for ONC RPC 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 binding protocols used in | ||||
conjunction with the ONC Remote Procedure Call (ONC RPC Version | ||||
2) protocols.</t></abstract></front> | ||||
<seriesInfo name='RFC' value='1833' /> | ||||
<format type='TXT' octets='24449' target='http://www.rfc-editor.org/rfc/rf | ||||
c1833.txt' /> | ||||
</reference> | ||||
<reference anchor="rpc_xid_issues"> | ||||
<front> | ||||
<title>RPC XID Issues</title> | ||||
<author initials="R." surname="Werme" fullname="Ric Werme"> | <reference anchor="rpc_xid_issues"> | |||
<organization>Digital Equipment Corporation</organization> | <front> | |||
</author> | <title>RPC XID Issues</title> | |||
<date month="February" year="1996"/> | <author initials="R." surname="Werme" fullname="Ric Werme"> | |||
<abstract> | <organization>Digital Equipment Corporation</organization> | |||
<t> | </author> | |||
<date month="February" year="1996"/> | ||||
<abstract> | ||||
<t> | ||||
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> | |||
<seriesInfo name="USENIX Conference Proceedings" value="" /> | <refcontent>USENIX Conference Proceedings</refcontent> | |||
</reference> | </reference> | |||
<reference anchor='RFC1094'> | ||||
<front> | ||||
<title abbrev='NFS: Network File System'>NFS: Network File System Protocol speci | ||||
fication</title> | ||||
<author initials='B.' surname='Nowicki' fullname='Bill Nowicki'> | ||||
<organization>Sun Microsystems, Inc.</organization> | ||||
<address> | ||||
<postal> | ||||
<street>2550 Garcia Avenue</street> | ||||
<street>Mail Stop 1-40</street> | ||||
<city>Mountain View</city> | ||||
<region>CA</region> | ||||
<code>94043</code> | ||||
<country>US</country></postal> | ||||
<phone>+1 415 336 7278</phone> | ||||
<email>nowicki@SUN.COM</email></address></author> | ||||
<date year='1989' month='March' /></front> | ||||
<seriesInfo name='RFC' value='1094' /> | ||||
<format type='TXT' octets='51454' target='http://www.rfc-editor.org/rfc/rfc1094. | ||||
txt' /> | ||||
</reference> | ||||
<reference anchor="ha_nfs_ibm"> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<front> | FC.1094.xml"/> | |||
<title>A Highly Available Network Server</title> | ||||
<author initials="A." surname="Bhide" fullname="Anupam Bhide"> | <reference anchor="ha_nfs_ibm"> | |||
<organization>IBM T.J. Watson Research Center</organization> | <front> | |||
</author> | <title>A Highly Available Network Server</title> | |||
<author initials="E. N." surname="Elnozahy" fullname="Elmootazbellah | <author initials="A." surname="Bhide" fullname="Anupam Bhide"> | |||
N. Elnozahy"> | <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 | |||
<author initials="S. P." surname="Morgan" fullname="Stephen P. Morgan | 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. Morga | |||
<date month="January" year="1991"/> | n "> | |||
<abstract> | <organization>IBM T.J. Watson Research Center</organization> | |||
<t> | </author> | |||
<date month="January" year="1991"/> | ||||
<abstract> | ||||
<t> | ||||
This paper presents the design and implementation | This paper presents the design and implementation | |||
of a Highly Available Network File Server | of a Highly Available Network File Server | |||
(HA-NFS). We separate the problem of network | (HA-NFS). We separate the problem of network | |||
file server reliability into three different subproblems: | file server reliability into three different subproblems: | |||
server reliability, disk reliability, and network | server reliability, disk reliability, and network | |||
reliability. HA-NFS offers a different solution | reliability. HA-NFS offers a different solution | |||
for each: dual-ported disks and impersonation | for each: dual-ported disks and impersonation | |||
are used to provide server reliability, disk mirroring | are used to provide server reliability, disk mirroring | |||
can be used to provide disk reliability, and optional | can be used to provide disk reliability, and optional | |||
network replication can be used to provide | network replication can be used to provide | |||
network reliability. The implementation shows | network reliability. The implementation shows | |||
that HA-NFS provides high availability without | that HA-NFS provides high availability without | |||
the excessive resource overhead or the performance | the excessive resource overhead or the performance | |||
degradation that characterize traditional replication | degradation that characterize traditional replication | |||
methods. Ongoing operations are not aborted | methods. Ongoing operations are not aborted | |||
during fail-over and recovery is completely transparent | during fail-over and recovery is completely transparent | |||
to applications. HA-NFS adheres to the | to applications. HA-NFS adheres to the | |||
NFS protocol standard and can be used by existing | NFS protocol standard and can be used by existing | |||
NFS clients without modification. | NFS clients without modification. | |||
</t> | </t> | |||
</abstract> | </abstract> | |||
</front> | </front> | |||
<seriesInfo name="USENIX Conference Proceedings" value="" /> | <refcontent>USENIX Conference Proceedings</refcontent> | |||
</reference> | </reference> | |||
<reference anchor='RFC5664'> | ||||
<front> | ||||
<title> | ||||
Object-Based Parallel NFS (pNFS) Operations | ||||
</title> | ||||
<author initials='B' surname='Halevy' fullname='Benny Halevy'> | ||||
<organization /> | ||||
</author> | ||||
<author initials='B' surname='Welch' fullname='Brent Welch'> | ||||
<organization /> | ||||
</author> | ||||
<author initials='J' surname='Zelenka' fullname='Jim Zelenka'> | ||||
<organization /> | ||||
</author> | ||||
<date month='January' year='2010' /> | ||||
<abstract><t>This Internet-Draft provides a description of the object-based pNFS | ||||
extension for NFSv4. This is a companion to the main pnfs specification in the | ||||
NFSv4 Minor Version 1 Internet Draft, which is currently draft-ietf-nfsv4-minor | ||||
version1-23.</t></abstract> | ||||
</front> | ||||
<seriesInfo name='RFC' value='5664' /> | ||||
<format type='TXT' | ||||
target='http://www.ietf.org/internet-drafts/draft-ietf-nfsv4-pnfs-obj-12 | ||||
.txt' /> | ||||
</reference> | ||||
<reference anchor='RFC5663'> | ||||
<front> | ||||
<title> | ||||
Parallel NFS (pNFS) Block/Volume Layout | ||||
</title> | ||||
<author initials='D' surname='Black' fullname='David Black'> | ||||
<organization /> | ||||
</author> | ||||
<author initials='J' surname='Glasgow' fullname='Jason Glasgow'> | ||||
<organization /> | ||||
</author> | ||||
<author initials='S' surname='Fridella' fullname='Stephen Fridella'> | ||||
<organization /> | ||||
</author> | ||||
<date month='January' year='2010' /> | ||||
<abstract><t>Parallel NFS (pNFS) extends NFSv4 to allow clients to | ||||
directly access file data on the storage used by the NFSv4 server. | ||||
This ability to bypass the server for data access can increase both | ||||
performance and parallelism, but requires additional client | ||||
functionality for data access, some of which is dependent on the class | ||||
of storage used. The main pNFS operations draft specifies | ||||
storage-class-independent extensions to NFS; this draft specifies the | ||||
additional extensions (primarily data structures) for use of pNFS with | ||||
block and volume based storage.</t></abstract> | ||||
</front> | ||||
<seriesInfo name='RFC' value='5663' /> | ||||
<format type='TXT' | ||||
target='http://www.ietf.org/internet-drafts/draft-ietf-nfsv4-pnfs-block- | ||||
11.txt' /> | ||||
</reference> | ||||
<reference anchor='RFC2054'> | ||||
<front> | ||||
<title>WebNFS Client Specification</title> | ||||
<author initials='B.' surname='Callaghan' fullname='Brent Callaghan'> | ||||
<organization>Sun Microsystems, Inc.</organization> | ||||
<address> | ||||
<postal> | ||||
<street>2550 Garcia Avenue</street> | ||||
<street>Mailstop Mpk17-201</street> | ||||
<city>Mountain View</city> | ||||
<region>CA</region> | ||||
<code>94043-1100</code> | ||||
<country>US</country></postal> | ||||
<phone>+1 415 786 5067</phone> | ||||
<facsimile>+1 415 786 5896</facsimile> | ||||
<email>brent.callaghan@eng.sun.com</email></address></author> | ||||
<date year='1996' month='October' /> | ||||
<abstract> | ||||
<t>This document describes a lightweight binding mechanism that allows | ||||
NFS clients to obtain service from WebNFS-enabled servers with a | ||||
minimum of protocol overhead. In removing this overhead, WebNFS | ||||
clients see benefits in faster response to requests, easy transit of | ||||
packet filter firewalls and TCP-based proxies, and better server | ||||
scalability.</t></abstract></front> | ||||
<seriesInfo name='RFC' value='2054' /> | ||||
<format type='TXT' octets='36354' target='http://www.rfc-editor.org/rfc/rf | ||||
c2054.txt' /> | ||||
</reference> | ||||
<reference anchor='RFC2055'> | ||||
<front> | ||||
<title>WebNFS Server Specification</title> | ||||
<author initials='B.' surname='Callaghan' fullname='Brent Callaghan'> | ||||
<organization>Sun Microsystems, Inc.</organization> | ||||
<address> | ||||
<postal> | ||||
<street>2550 Garcia Avenue</street> | ||||
<street>Mailstop Mpk17-201</street> | ||||
<city>Mountain View</city> | ||||
<region>CA</region> | ||||
<code>94043-1100</code> | ||||
<country>US</country></postal> | ||||
<phone>+1 415 786 5067</phone> | ||||
<facsimile>+1 415 786 5896</facsimile> | ||||
<email>brent.callaghan@eng.sun.com</email></address></author> | ||||
<date year='1996' month='October' /> | ||||
<abstract> | ||||
<t>This document describes the specifications for a server of WebNFS | ||||
clients. WebNFS extends the semantics of the NFSv3 | ||||
protocol to allow clients to obtain filehandles more easily, without | ||||
recourse to the portmap or MOUNT protocols. In removing the need for | ||||
these protocols, WebNFS clients see benefits in faster response to | ||||
requests, easy transit of firewalls and better server scalability Thi | ||||
s | ||||
description is provided to facilitate compatible implementations of | ||||
WebNFS servers.</t></abstract></front> | ||||
<seriesInfo name='RFC' value='2055' /> | ||||
<format type='TXT' octets='20498' target='http://www.rfc-editor.org/rfc/rf | ||||
c2055.txt' /> | ||||
</reference> | ||||
<reference anchor="errata"> | ||||
<front> | ||||
<title>IESG Processing of RFC Errata for the IETF Stream | ||||
</title> | ||||
<author> | ||||
<organization>IESG | ||||
</organization> | ||||
</author> | ||||
<date month="July" year="2008" /> | ||||
</front> | ||||
<format type='TXT' target='http://www.ietf.org/IESG/STATEMENTS/iesg-statem | ||||
ent-07-30-2008.txt' /> | ||||
</reference> | ||||
<reference anchor='RFC2104'> | ||||
<front> | ||||
<title abbrev='HMAC'>HMAC: Keyed-Hashing for Message Authentication</titl | ||||
e> | ||||
<author initials='H.' surname='Krawczyk' fullname='Hugo Krawczyk'> | ||||
<organization>IBM, T.J. Watson Research Center</organization> | ||||
<address> | ||||
<postal> | ||||
<street>P.O.Box 704</street> | ||||
<city>Yorktown Heights</city> | ||||
<region>NY</region> | ||||
<code>10598</code> | ||||
<country>US</country></postal> | ||||
<email>hugo@watson.ibm.com</email></address></author> | ||||
<author initials='M.' surname='Bellare' fullname='Mihir Bellare'> | ||||
<organization>University of California at San Diego, Dept of Computer S | ||||
cience and Engineering</organization> | ||||
<address> | ||||
<postal> | ||||
<street>9500 Gilman Drive</street> | ||||
<street>Mail Code 0114</street> | ||||
<city>La Jolla</city> | ||||
<region>CA</region> | ||||
<code>92093</code> | ||||
<country>US</country></postal> | ||||
<email>mihir@cs.ucsd.edu</email></address></author> | ||||
<author initials='R.' surname='Canetti' fullname='Ran Canetti'> | ||||
<organization>IBM T.J. Watson Research Center</organization> | ||||
<address> | ||||
<postal> | ||||
<street>P.O.Box 704</street> | ||||
<city>Yorktown Heights</city> | ||||
<region>NY</region> | ||||
<code>10598</code> | ||||
<country>US</country></postal> | ||||
<email>canetti@watson.ibm.com</email></address></author> | ||||
<date year='1997' month='February' /> | ||||
<abstract> | ||||
<t>This document describes HMAC, a mechanism for message | ||||
authentication using cryptographic hash functions. HMAC can | ||||
be used with any iterative cryptographic hash function, | ||||
e.g., MD5, SHA-1, in combination with a secret shared key. | ||||
The cryptographic strength of HMAC depends on the properties | ||||
of the underlying hash function.</t></abstract></front> | ||||
<seriesInfo name='RFC' value='2104' /> | ||||
<format type='TXT' octets='22297' target='http://www.rfc-editor.org/rfc/rf | ||||
c2104.txt' /> | ||||
</reference> | ||||
<reference anchor='RFC2624'> | ||||
<front> | ||||
<title abbrev='NFSv4 Design Considerations'>NFS Version 4 Design Considerations< | ||||
/title> | ||||
<author initials='S.' surname='Shepler' fullname='Spencer Shepler'> | ||||
<organization>Sun Microsystems, Inc.</organization> | ||||
<address> | ||||
<postal> | ||||
<street>7808 Moonflower Drive</street> | ||||
<city>Austin</city> | ||||
<region>TX</region> | ||||
<code>78750</code> | ||||
<country>US</country></postal> | ||||
<phone>+1 512 349 9376</phone> | ||||
<email>spencer.shepler@eng.sun.com</email></address></author> | ||||
<date year='1999' month='June' /> | ||||
<abstract> | ||||
<t>The main task of the NFSv4 working group is to create a | ||||
protocol definition for a distributed file system that focuses on the | ||||
following items: improved access and good performance on the Internet, | ||||
strong security with negotiation built into the protocol, better | ||||
cross-platform interoperability, and designed for protocol extensions. | ||||
NFSv4 will owe its general design to the previous versions of | ||||
NFS. It is expected, however, that many features will be quite | ||||
different in NFSv4 than previous versions to facilitate the | ||||
goals of the working group and to address areas that NFSv2 and | ||||
NFSv3 have not.</t> | ||||
<t>This design considerations document is meant to present more detail | ||||
than the working group charter. Specifically, it presents the areas | ||||
that the working group will investigate and consider while developing | ||||
a protocol specification for NFSv4. Based on this | ||||
investigation the working group will decide the features of the new | ||||
protocol based on the cost and benefits within the specific feature | ||||
areas.</t></abstract> <note title='Key Words'> | ||||
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | ||||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | ||||
document are to be interpreted as described in RFC | ||||
2119.</t></note></front> | ||||
<seriesInfo name='RFC' value='2624' /> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<format type='TXT' octets='52891' target='http://www.rfc-editor.org/rfc/rfc2624. | FC.5664.xml"/> | |||
txt' /> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
</reference> | FC.5663.xml"/> | |||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.2054.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.2055.xml"/> | ||||
<reference anchor="xnfs"> | <reference anchor="errata" target="https://www.ietf.org/about/groups/ies | |||
<front> | g/statements/processing-rfc-errata/"> | |||
<title> Protocols for Interworking: XNFS, Version 3W, ISBN 1-85912-18 | <front> | |||
4-5 </title> | <title>IESG Processing of RFC Errata for the IETF Stream | |||
</title> | ||||
<author> | ||||
<organization>IESG | ||||
</organization> | ||||
</author> | ||||
<date month="July" year="2008"/> | ||||
</front> | ||||
</reference> | ||||
<author> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<organization>The Open Group </organization> | FC.2104.xml"/> | |||
</author> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<date month="February" year="1998"/> | FC.2624.xml"/> | |||
</front> | ||||
</reference> | ||||
<reference anchor="Floyd"> | <reference anchor="xnfs"> | |||
<front> | <front> | |||
<title> The Synchronization of Periodic Routing Messages </title> | <title> Protocols for Interworking: XNFS, Version 3W</title> | |||
<seriesInfo name="ISBN" value="1-85912-184-5"/> | ||||
<author> | ||||
<organization>The Open Group </organization> | ||||
</author> | ||||
<date month="February" year="1998"/> | ||||
</front> | ||||
</reference> | ||||
<author initials="S." surname="Floyd" > | <reference anchor="Floyd"> | |||
<organization></organization> | <front> | |||
<title> The Synchronization of Periodic Routing Messages </title> | ||||
<author initials="S." surname="Floyd"> | ||||
<organization/> | ||||
</author> | </author> | |||
<author initials="V." surname="Jacobson"> | <author initials="V." surname="Jacobson"> | |||
<organization></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</re | ||||
<seriesInfo name="IEEE/ACM Transactions on Networking" value="2(2), pp. | fcontent> | |||
122-136" /> | </reference> | |||
</reference> | ||||
<reference anchor="RFC3720"> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<front> | FC.7143.xml"/> | |||
<title>Internet Small Computer Systems Interface (iSCSI)</title> | ||||
<author initials="J." surname="Satran" fullname="J. Satran"> | ||||
<organization/> | ||||
</author> | ||||
<author initials="K." surname="Meth" fullname="K. Meth"> | ||||
<organization/> | ||||
</author> | ||||
<author initials="C." surname="Sapuntzakis" fullname="C. Sapuntzakis"> | ||||
<organization/> | ||||
</author> | ||||
<author initials="M." surname="Chadalapaka" fullname="M. Chadalapaka"> | ||||
<organization/> | ||||
</author> | ||||
<author initials="E." surname="Zeidner" fullname="E. Zeidner"> | ||||
<organization/> | ||||
</author> | ||||
<date year="2004" month="April"/> | ||||
</front> | ||||
<seriesInfo name="RFC" value="3720"/> | ||||
<format type="TXT" octets="578468" target="http://www.rfc-editor.org/rfc/r | ||||
fc3720.txt"/> | ||||
</reference> | ||||
<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> | |||
<seriesInfo name="ANSI/INCITS" value="350-2003" /> | <refcontent>ANSI/INCITS, 350-2003</refcontent> | |||
</reference> | </reference> | |||
<reference anchor='OSD-T10' | <reference anchor="OSD-T10" target="https://www.t10.org/drafts.htm"> | |||
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> | |||
<seriesInfo name="ANSI/INCITS" value="400-2004"/> | </reference> | |||
</reference> | ||||
<reference anchor="PVFS"> | <reference anchor="PVFS"> | |||
<front> | <front> | |||
<title>PVFS: A Parallel File System for Linux Clusters.</title> | <title>PVFS: A Parallel File System for Linux Clusters.</title> | |||
<author initials="P. H." surname="Carns"> | ||||
<author initials="P. H." surname="Carns"> | <organization> Parallel Architecture Research Laboratory, | |||
<organization> Parallel Architecture Research Laboratory, | ||||
Clemson University, Clemson, SC 29634 </organization> | Clemson University, Clemson, SC 29634 </organization> | |||
</author> | ||||
</author> | <author initials="W. B." surname="Ligon III"> | |||
<author initials="W. B." surname="Ligon III"> | <organization> Parallel Architecture Research Laboratory, | |||
<organization> Parallel Architecture Research Laboratory, | ||||
Clemson University, Clemson, SC 29634 </organization> | Clemson University, Clemson, SC 29634 </organization> | |||
</author> | </author> | |||
<author initials="R. B." surname="Ross"> | ||||
<author initials="R. B." surname="Ross"> | <organization> Parallel Architecture Research Laboratory, | |||
<organization> Parallel Architecture Research Laboratory, | ||||
Clemson University, Clemson, SC 29634 </organization> | Clemson University, Clemson, SC 29634 </organization> | |||
</author> | </author> | |||
<author initials="R." surname="Thakur"> | ||||
<author initials="R." surname="Thakur"> | <organization>Mathematics and Computer Science Division, | |||
<organization>Mathematics and Computer Science Division, | ||||
Argonne National Laboratory, Argonne, IL 60439</organization> | Argonne National Laboratory, Argonne, IL 60439</organization> | |||
</author> | </author> | |||
<date year="2000"/> | ||||
<date year="2000"/> | </front> | |||
</front> | <refcontent>Proceedings of the 4th Annual Linux Showcase and Conferenc | |||
<seriesInfo name="Proceedings of the 4th Annual Linux Showcase and Confe | e</refcontent> | |||
rence" value=""/> | </reference> | |||
</reference> | ||||
<reference anchor="access_api"> | <reference anchor="access_api" target="https://www.opengroup.org"> | |||
<front> | <front> | |||
<title>The Open Group Base Specifications Issue 6, IEEE Std 1003.1, 2004 Ed | <title>The Open Group Base Specifications Issue 6, IEEE Std 1003.1, | |||
ition | 2004 Edition | |||
</title> | </title> | |||
<author> | <author> | |||
<organization>The Open Group | <organization>The Open Group | |||
</organization> | </organization> | |||
</author> | </author> | |||
<date year="2004" /> | <date year="2004"/> | |||
<abstract> | <abstract> | |||
<t> | <t> | |||
The description of the access() function states: "If the process has a ppropriate privileges, an implementation may indicate success for X_OK even if n one of the execute file permission bits are set." | The description of the access() function states: "If the process has a ppropriate privileges, an implementation may indicate success for X_OK even if n one of the execute file permission bits are set." | |||
</t> | </t> | |||
</abstract> | </abstract> | |||
</front> | ||||
</front> | </reference> | |||
</reference> | ||||
<reference anchor='RFC2224'> | ||||
<front> | ||||
<title>NFS URL Scheme</title> | ||||
<author initials='B.' surname='Callaghan' fullname='Brent Callaghan'> | ||||
<organization>Sun Microsystems, Inc.</organization> | ||||
<address> | ||||
<postal> | ||||
<street>Mailstop Mpk17-201</street> | ||||
<street>901 San Antonio Road</street> | ||||
<street>Palo Alto</street> | ||||
<street>California 94303</street></postal> | ||||
<phone>1-415-786-5067</phone> | ||||
<facsimile>1-415-786-5896</facsimile> | ||||
<email>brent.callaghan@eng.sun.com</email></address></author> | ||||
<date year='1997' month='October' /> | ||||
<area>Applications</area> | ||||
<keyword>NFS</keyword> | ||||
<keyword>network file system</keyword> | ||||
<keyword>uniform resource</keyword> | ||||
<abstract> | ||||
<t> | ||||
A new URL scheme, 'nfs' is defined. It is used to refer to files a | ||||
nd | ||||
directories on NFS servers using the general URL syntax defined in | ||||
RFC 1738, "Uniform Resource Locators (URL)". | ||||
</t> | ||||
<t> | ||||
This scheme uses the public filehandle and multi-component look up | ||||
[RFC2054, RFC2055] to access server data with a minimum of protocol | ||||
overhead. | ||||
</t> | ||||
<t> | ||||
The NFS protocol provides access to shared file systems across | ||||
networks. It is designed to be machine, operating system, network | ||||
architecture, and transport protocol independent. | ||||
</t></abstract></front> | ||||
<seriesInfo name='RFC' value='2224' /> | ||||
<format type='TXT' octets='22726' target='http://www.rfc-editor.org/rfc/rfc2224. | ||||
txt' /> | ||||
<format type='HTML' octets='35259' target='http://xml.resource.org/public/rfc/ht | ||||
ml/rfc2224.html' /> | ||||
<format type='XML' octets='24805' target='http://xml.resource.org/public/rfc/xml | ||||
/rfc2224.xml' /> | ||||
</reference> | ||||
<reference anchor='RFC2755'> | ||||
<front> | ||||
<title>Security Negotiation for WebNFS</title> | ||||
<author initials='A.' surname='Chiu' fullname='Alex Chiu'> | ||||
<organization>Sun Microsystems, Inc.</organization> | ||||
<address> | ||||
<postal> | ||||
<street>901 San Antonio Road</street> | ||||
<city>Palo Alto</city> | ||||
<region>CA</region> | ||||
<code>94303</code> | ||||
<country>US</country></postal> | ||||
<phone>+1 650 786 6465</phone> | ||||
<email>alex.chiu@Eng.sun.com</email></address></author> | ||||
<author initials='M.' surname='Eisler' fullname='Mike Eisler'> | ||||
<organization>Sun Microsystems, Inc.</organization> | ||||
<address> | ||||
<postal> | ||||
<street>901 San Antonio Road</street> | ||||
<city>Palo Alto</city> | ||||
<region>CA</region> | ||||
<code>94303</code> | ||||
<country>US</country></postal> | ||||
<phone>+1 719 599 9026</phone> | ||||
<email>michael.eisler@Eng.sun.com</email></address></author> | ||||
<author initials='B.' surname='Callaghan' fullname='Brent Callaghan'> | ||||
<organization>Sun Microsystems, Inc.</organization> | ||||
<address> | ||||
<postal> | ||||
<street>901 San Antonio Road</street> | ||||
<city>Palo Alto</city> | ||||
<region>CA</region> | ||||
<code>94303</code> | ||||
<country>US</country></postal> | ||||
<phone>+1 650 786 5067</phone> | ||||
<email>brent.callaghan@Eng.sun.com</email></address></author> | ||||
<date year='2000' month='January' /> | ||||
<abstract> | ||||
<t>This document describes a protocol for a WebNFS clientto negotiate the desire | ||||
d security mechanism with a WebNFS serverbefore the WebNFS client falls back to | ||||
the MOUNT v3 protocol. This document is provided so that people can write compat | ||||
ible implementations.</t></abstract></front> | ||||
<seriesInfo name='RFC' value='2755' /> | ||||
<format type='TXT' octets='23493' target='http://www.rfc-editor.org/rfc/rfc2755. | ||||
txt' /> | ||||
</reference> | ||||
<reference anchor='RFC5226'> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
FC.2224.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.2755.xml"/> | ||||
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | ||||
FC.8126.xml"/> | ||||
<front> | <reference anchor="Err2006" quote-title="false" target="https://www.rfc- | |||
<title>Guidelines for Writing an IANA Considerations Section in RFCs</title> | editor.org/errata/eid2006"> | |||
<author initials='T.' surname='Narten' fullname='T. Narten'> | <front> | |||
<organization /></author> | <title>Erratum ID 2006</title> | |||
<author initials='H.' surname='Alvestrand' fullname='H. Alvestrand'> | <author> | |||
<organization /></author> | <organization>RFC Errata</organization> | |||
<date year='2008' month='May' /> | </author> | |||
<abstract> | </front> | |||
<t>Many protocols make use of identifiers consisting of constants and other w | <refcontent>RFC 5661</refcontent> | |||
ell-known values. Even after a protocol has been defined and deployment has begu | </reference> | |||
n, new values may need to be assigned (e.g., for a new option type in DHCP, or a | ||||
new encryption or authentication transform for IPsec). To ensure that such quan | ||||
tities have consistent values and interpretations across all implementations, th | ||||
eir assignment must be administered by a central authority. For IETF protocols, | ||||
that role is provided by the Internet Assigned Numbers Authority (IANA).</t>& | ||||
lt;t> In order for IANA to manage a given namespace prudently, it needs guidelin | ||||
es describing the conditions under which new values can be assigned or when modi | ||||
fications to existing values can be made. If IANA is expected to play a role in | ||||
the management of a namespace, IANA must be given clear and concise instructions | ||||
describing that role. This document discusses issues that should be considered | ||||
in formulating a policy for assigning values to a namespace and provides guideli | ||||
nes for authors on the specific text that must be included in documents that pla | ||||
ce demands on IANA.</t><t> This document obsoletes RFC 2434. This document | ||||
specifies an Internet Best Current Practices for the Internet Community, and re | ||||
quests discussion and suggestions for improvements.</t></abstract></front> | ||||
<seriesInfo name='BCP' value='26' /> | <reference anchor="AFS"> | |||
<seriesInfo name='RFC' value='5226' /> | <front> | |||
<format type='TXT' octets='66160' target='http://www.rfc-editor.org/rfc/rfc52 | <title> | |||
26.txt' /> | ||||
</reference> | ||||
<reference anchor="Err2006" | ||||
target="https://www.rfc-editor.org/errata_search.php?eid=2006"> | ||||
<front> | ||||
<title>Errata 2006 for RFC 5661</title> | ||||
<author initials='M.' surname='Eisler' fullname='Mike Eisler'> | ||||
</author> | ||||
<date year='2010' month='January' /> | ||||
</front> | ||||
</reference> | ||||
<reference anchor="AFS" | ||||
target="https://www.cs.cmu.edu/~satya/docdir/spasojevic-tocs-afs-m | ||||
easurement-1996.pdf"> | ||||
<front> | ||||
<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 Spasoje | |||
vic"> | ||||
</author> | </author> | |||
<author initials='M.' surname='Satayanarayanan' fullname='Mahadev Satayan arayanan'> | <author initials="M." surname="Satayanarayanan" fullname="Mahadev Sa tayanarayanan"> | |||
</author> | </author> | |||
<date year='1996' month='May' /> | <date year="1996" month="May"/> | |||
</front> | </front> | |||
</reference> | <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> | ||||
<?rfc include="reference.RFC.5661.xml"?> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<?rfc include="reference.RFC.8178.xml"?> | FC.5661.xml"/> | |||
<?rfc include="reference.RFC.7530.xml"?> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<?rfc include="reference.RFC.7931.xml"?> | FC.8178.xml"/> | |||
<?rfc include="reference.RFC.8434.xml"?> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<?rfc include="reference.RFC.7258.xml"?> | FC.7530.xml"/> | |||
<?rfc include="reference.RFC.3552.xml"?> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
</references> | FC.7931.xml"/> | |||
<!-- $Id: 2009-12-20-TO-rfc5661.xml,v 1.2 2009/12/21 05:59:32 shepler.mre Exp | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
$ --> | FC.8434.xml"/> | |||
<!-- Copyright (C) The IETF Trust (2007-2008) --> | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
<!-- Copyright (C) The Internet Society (2006) --> | FC.7258.xml"/> | |||
<section anchor="NEED" | <xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R | |||
title="Need for this Update"> | FC.3552.xml"/> | |||
<t> | </references> | |||
This document includes an explanation of how clients and | </references> | |||
servers are to determine | <section anchor="NEED" numbered="true" toc="default"> | |||
the particular network access paths to be used to access a | <name>The Need for This Update</name> | |||
file system. This includes describing | <t> | |||
how changes to the specific replica to be used or to | This document includes an explanation of how clients and servers | |||
the set of addresses to be used to access it are to be | are to determine the particular network access paths to be used to access | |||
dealt with, and how transfers of responsibility that need to be | a | |||
made can be dealt with transparently. This includes cases in which | file system. This includes descriptions of | |||
how to handle changes to the specific replica to be used or to | ||||
the set of addresses to be used to access it, | ||||
and how to deal transparently with transfers of responsibility that need t | ||||
o be | ||||
made. This includes cases in which | ||||
there is a shift between one replica and another and those in | there is a shift between one replica and another and those in | |||
which different network access paths are used to access the | which different network access paths are used to access the | |||
same replica. | same replica. | |||
</t> | </t> | |||
<t> | ||||
As a result of the following problems in RFC5661 | ||||
<xref target="RFC5661"/>, it | ||||
is necessary to provide the specific updates which are made by this | ||||
document. These updates are described in <xref target="CHG"/> | ||||
<list style="symbols"> | ||||
<t> | <t> | |||
RFC5661 <xref target="RFC5661"/>, while it dealt with situations in | As a result of the following problems in RFC 5661 | |||
which various forms of clustering allowed co-ordination | <xref target="RFC5661" format="default"/>, it | |||
of the state assigned by co-operating servers to be used, | was necessary to provide the specific updates that are made by this | |||
document. These updates are described in <xref target="CHG" format="defaul | ||||
t"/>. | ||||
</t> | ||||
<ul spacing="normal"> | ||||
<li> | ||||
RFC 5661 <xref target="RFC5661" format="default"/>, while it dealt with s | ||||
ituations in | ||||
which various forms of clustering allowed coordination | ||||
of the state assigned by cooperating servers to be used, | ||||
made no provisions for Transparent State Migration. Within NFSv4.0, | made no provisions for Transparent State Migration. Within NFSv4.0, | |||
Transparent Migration was first explained clearly in | Transparent State Migration was first explained clearly in | |||
RFC7530 <xref target="RFC7530"/> and corrected and | RFC 7530 <xref target="RFC7530" format="default"/> and corrected and | |||
clarified by RFC7931 <xref target="RFC7931"/>. No corresponding | clarified by RFC 7931 <xref target="RFC7931" format="default"/>. No corr | |||
esponding | ||||
explanation for NFSv4.1 had been provided. | explanation for NFSv4.1 had been provided. | |||
</t> | </li> | |||
<t> | <li> | |||
Although NFSv4.1 was defined with a clear definition of how | Although NFSv4.1 provided a clear definition of how | |||
trunking detection was to be done, there was no clear specification | trunking detection was to be done, there was no clear specification | |||
of how trunking discovery was to be done, despite the fact that | of how trunking discovery was to be done, despite the fact that | |||
the specification clearly indicated that this information | the specification clearly indicated that this information | |||
could be made available via the file system location attributes. | could be made available via the file system location attributes. | |||
</t> | </li> | |||
<t> | <li> | |||
Because the existence of multiple network access paths to the same | Because the existence of multiple network access paths to the same | |||
file system was | file system was dealt with as if there were multiple replicas, issues re | |||
dealt with as if there were multiple replicas, issues relating to | lating to | |||
transitions between replicas could never be clearly distinguished | transitions between replicas could never be clearly distinguished | |||
from trunking-related transitions between the addresses used to | from trunking-related transitions between the addresses used to | |||
access a particular file system instance. | access a particular file system instance. As a result, in situations i | |||
As a result, in situations in | n | |||
which both migration and trunking configuration changes | which both migration and trunking configuration changes | |||
were involved, neither of these | were involved, neither of these could be clearly dealt with, and the re | |||
could be clearly dealt with and the relationship between | lationship between | |||
these two features was not seriously addressed. | these two features was not seriously addressed. | |||
</t> | </li> | |||
<t> | <li> | |||
Because use of two network access paths to the same file system | Because use of two network access paths to the same file system | |||
instance | instance (i.e., trunking) was often treated as if two replicas were | |||
(i.e. trunking) was often treated as if two replicas were | involved, it was considered that two replicas were being used simultaneou | |||
involved, it was considered that | sly. | |||
two replicas were being used simultaneously. As a | As a result, the treatment of replicas being used simultaneously | |||
result, the treatment of replicas being used simultaneously | in RFC 5661 <xref target="RFC5661" format="default"/> was not clear, as i | |||
in RFC5661 <xref target="RFC5661" /> was not clear as it covered the | t covered the | |||
two distinct cases of a | two distinct cases of a single file system instance being accessed by | |||
single file system instance being accessed by | two different network access paths and two | |||
two different network access | ||||
paths and two | ||||
replicas being accessed simultaneously, with the limitations | replicas being accessed simultaneously, with the limitations | |||
of the latter case not being clearly laid out. | of the latter case not being clearly laid out. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | ||||
<t> | ||||
The majority of the consequences of these issues are dealt with | ||||
by presenting in <xref target="NEW11"/> a replacement for | ||||
Section 11 within RFC5661 <xref target="RFC5661"/>. This replacement | ||||
modifies existing sub-sections within that section and adds new | ||||
ones, as described in <xref target="CHG-11"/>. Also, some existing | ||||
sections are deleted. These changes | ||||
were made in order to: | ||||
<list style="symbols"> | ||||
<t> | <t> | |||
Reorganize the description so that the case | The majority of the consequences of these issues are dealt with | |||
of two network | by presenting in <xref target="NEW11" format="default"/> a replacement | |||
access paths to | for Section <xref target="RFC5661" sectionFormat="bare" section="11"/> | |||
the same file system instance | of RFC 5661 <xref target="RFC5661"/>. This replacement | |||
needs to be distinguished clearly from the case of | modifies existing subsections within that section and adds new | |||
two different replicas | ones as described in <xref target="CHG-11" format="default"/>. Also, som | |||
since, in the | e existing | |||
former case, locking state is shared and there also | sections were deleted. These changes were made in order to do the | |||
can be sharing of session state. | following: | |||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
Reorganize the description so that the case of two network access paths | ||||
to | ||||
the same file system instance is distinguished clearly from the case of | ||||
two different replicas since, in the former case, locking state is shared | ||||
and there also | ||||
can be sharing of session state. | ||||
</li> | ||||
<li> | ||||
Provide a clear statement regarding the desirability of | Provide a clear statement regarding the desirability of | |||
transparent transfer of state between replicas | transparent transfer of state between replicas together with a recommend | |||
together with a recommendation | ation | |||
that either that or a single-fs grace period be provided. | that either transparent transfer or a single-fs grace period be provided | |||
</t> | . | |||
<t> | </li> | |||
Specifically delineate how such transfers are to be dealt | <li> | |||
with by | Specifically delineate how a client is to handle such transfers, | |||
the client, taking into account the differences from the treatment | taking into account the differences from the treatment | |||
in <xref target="RFC7931"/> made necessary by the major protocol | in <xref target="RFC7931" format="default"/> made necessary by the major | |||
changes made in NFSv4.1. | protocol | |||
</t> | changes to NFSv4.1. | |||
<t> | </li> | |||
Provide discussion of the relationship between transparent | <li> | |||
Discuss the relationship between transparent | ||||
state transfer and Parallel NFS (pNFS). | state transfer and Parallel NFS (pNFS). | |||
</t> | </li> | |||
<t> | <li> | |||
Provide clarification of the fs_locations_info attribute | Clarify the fs_locations_info attribute in order to specify | |||
in order to specify | which portions of the provided information apply to a specific | |||
which portions of the information provided apply to a specific | network access path and which apply to the replica that the path | |||
network access path and which to the replica which that path | ||||
is used to access. | is used to access. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | ||||
<t> | ||||
In addition, there are also updates to other sections of | ||||
RFC5661 <xref target="RFC5661"/>, where the consequences of the | ||||
incorrect assumptions | ||||
underlying the current treatment of multi-server namespace | ||||
issues also needed to be corrected. These are to be dealt with as | ||||
described in Sections | ||||
<xref target="CHG-ops" format="counter"/> through | ||||
<xref target="CHG-other" format="counter"/>. | ||||
<list style="symbols"> | ||||
<t> | <t> | |||
In addition, other sections of RFC 5661 <xref target="RFC5661" format="def | ||||
ault"/> | ||||
were updated to correct the consequences of the | ||||
incorrect assumptions underlying the treatment of multi-server namespace | ||||
issues. These are described in Appendices <xref target="CHG-ops" format=" | ||||
counter"/> through | ||||
<xref target="CHG-other" format="counter"/>. | ||||
</t> | ||||
<ul spacing="normal"> | ||||
<li> | ||||
A revised introductory section regarding multi-server namespace | A revised introductory section regarding multi-server namespace | |||
facilities is provided. | facilities is provided. | |||
</t> | </li> | |||
<t> | <li> | |||
A more realistic treatment of server scope is provided, which | A more realistic treatment of server scope is provided. This treatment | |||
reflects the more limited co-ordination of locking state | reflects the more limited coordination of locking state | |||
adopted by servers actually sharing a common server scope. | adopted by servers actually sharing a common server scope. | |||
</t> | </li> | |||
<t> | <li> | |||
Some confusing text regarding changes in server_owner has | Some confusing text regarding changes in server_owner has | |||
been clarified. | been clarified. | |||
</t> | </li> | |||
<t> | <li> | |||
The description of some existing errors has been modified | The description of some existing errors has been modified | |||
to more clearly explain certain errors situations to reflect | to more clearly explain certain error situations to reflect | |||
the existence of trunking and the possible use of fs-specific grace | the existence of trunking and the possible use of fs-specific grace | |||
periods. For details, see <xref target="CHG-errs"/>. | periods. For details, see <xref target="CHG-errs" format="default"/>. | |||
</t> | </li> | |||
<t> | <li> | |||
New descriptions of certain existing operations are | New descriptions of certain existing operations are | |||
provided, either because the existing treatment did not | provided, either because the existing treatment did not | |||
account for situations that would arise in dealing with | account for situations that would arise in dealing with | |||
transparent state migration, or because some types of reclaim | Transparent State Migration, or because some types of reclaim | |||
issues were not adequately dealt with in the context of fs-specific | issues were not adequately dealt with in the context of fs-specific | |||
grace periods. For details, see <xref target="CHG-ops"/>. | grace periods. For details, see <xref target="CHG-ops" format="default"/> | |||
</t> | . | |||
</list> | </li> | |||
</t> | </ul> | |||
</section> | </section> | |||
<section anchor="CHG" numbered="true" toc="default"> | ||||
<section anchor="CHG" | <name>Changes in This Update</name> | |||
title="Changes in this Update"> | <section anchor="CHG-11" numbered="true" toc="default"> | |||
<section title="Revisions Made to Section 11 of RFC5661" | <name>Revisions Made to Section 11 of RFC 5661</name> | |||
anchor="CHG-11"> | <t> | |||
<t> | A number of areas have been revised or extended, in many cases | |||
A number of areas needed to be revised or extended, in many case | replacing subsections within Section | |||
replacing existing | <xref target="RFC5661" sectionFormat="bare" section="11"/> of RFC 5661 <xr | |||
sub-sections | ef target="RFC5661"/>: | |||
within section 11 of RFC5661 <xref target="RFC5661"/>: | </t> | |||
<list style="symbols"> | <ul spacing="normal"> | |||
<t> | <li> | |||
New introductory material, including a terminology section, | New introductory material, including a terminology section, | |||
replaces the existing material | replaces the material in RFC 5661 <xref target="RFC5661" format="default" | |||
in RFC5661 <xref target="RFC5661"/> | />, | |||
ranging from the start of the existing Section 11 | ranging from the start of the original Section | |||
up to and including the existing Section | <xref target="RFC5661" sectionFormat="bare" section="11"/> up to and inc | |||
11.1. The new material starts at the beginning of | luding | |||
<xref target="NEW11"/> and continues | Section <xref target="RFC5661" sectionFormat="bare" section="11.1"/>. | |||
through <xref target="SEC11-loc-attr" format="counter"/> | The new material starts at the beginning of | |||
below. | <xref target="NEW11" format="default"/> and continues | |||
</t> | through <xref target="SEC11-loc-attr" format="counter"/>. | |||
<t> | </li> | |||
A significant reorganization of the material in the | <li> | |||
existing Sections 11.4 and 11.5 (of RFC5661 | <t> | |||
<xref target="RFC5661"/>) | A significant reorganization of the material in Sections | |||
is necessary. | <xref target="RFC5661" sectionFormat="bare" section="11.4"/> and | |||
The reasons for the reorganization of | <xref target="RFC5661" sectionFormat="bare" section="11.5"/> of RFC 5661 | |||
<xref target="RFC5661"/> was necessary. The reasons for the reorganizati | ||||
on of | ||||
these sections into a single section with multiple subsections | these sections into a single section with multiple subsections | |||
are discussed in | are discussed in <xref target="SEC11-uses-reorg" format="default"/> belo | |||
<xref target="SEC11-uses-reorg"/> below. | w. | |||
This replacement appears as <xref target="SEC11-USES"/> | This replacement appears as <xref target="SEC11-USES" format="default"/>. | |||
below. | </t> | |||
<vspace blankLines='1' /> | <t> | |||
New material relating to the handling of the file system location | New material relating to the handling of the file system location | |||
attributes is contained | attributes is contained in Sections <xref target="SEC11-USES-mult" forma | |||
in Sections <xref target="SEC11-USES-mult" format="counter"/> and | t="counter"/> and | |||
<xref target="SEC11-USES-changes" format="counter"/> below. | <xref target="SEC11-USES-changes" format="counter"/>. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
A new section describing requirements for user and group | A new section describing requirements for user and group | |||
handling within a multi-server namespace has been added as | handling within a multi-server namespace has been added as | |||
<xref target="SEC11-users"/> | <xref target="SEC11-users" format="default"/>. | |||
</t> | </li> | |||
<t> | <li> | |||
A major replacement for the existing Section 11.7 of | A major replacement for Section | |||
RFC5661 <xref target="RFC5661" /> entitled | <xref target="RFC5661" sectionFormat="bare" section="11.7"/> of RFC 5661 | |||
"Effecting File System Transitions", will appear as Sections | <xref target="RFC5661"/>, | |||
<xref target="SEC11-trans-oview" format="counter"/> | entitled "Effecting File System Transitions", appears as Sections | |||
through <xref target="SEC11-trans-server" format="counter"/>. | <xref target="SEC11-trans-oview" format="counter"/> through | |||
<xref target="SEC11-trans-server" format="counter"/>. | ||||
The reasons for the reorganization of | The reasons for the reorganization of | |||
this section into multiple sections are discussed in | this section into multiple sections are discussed in | |||
<xref target="SEC11-trans-reorg"/>. | <xref target="SEC11-trans-reorg" format="default"/>. | |||
</t> | </li> | |||
<t> | <li> | |||
A replacement for the existing Section 11.10 of | A replacement for Section | |||
RFC5661 <xref target="RFC5661" /> entitled | <xref target="RFC5661" sectionFormat="bare" section="11.10"/> of RFC 566 | |||
"The Attribute fs_locations_info", will appear as | 1 <xref target="RFC5661"/>, | |||
<xref target="SEC11-li-new"/>, with | entitled "The Attribute fs_locations_info", appears as | |||
<xref target="SEC11-li-changes"/> describing the differences | <xref target="SEC11-li-new" format="default"/>, with | |||
<xref target="SEC11-li-changes" format="default"/> describing the differe | ||||
nces | ||||
between the new section and the treatment within | between the new section and the treatment within | |||
<xref target="RFC5661" />. | <xref target="RFC5661" format="default"/>. | |||
A revised treatment is necessary because the existing treatment | A revised treatment was necessary because the original treatment | |||
did not make clear how the added attribute information relates | did not make clear how the added attribute information relates | |||
to the case of trunked paths to the same replica. These issues | to the case of trunked paths to the same replica. These issues | |||
were not addressed in RFC5661 <xref target="RFC5661" /> where the | were not addressed in RFC 5661 <xref target="RFC5661" format="default"/> where the | |||
concepts of a replica and a network path used to access a replica | concepts of a replica and a network path used to access a replica | |||
were not clearly distinguished. | were not clearly distinguished. | |||
</t> | </li> | |||
</list> | </ul> | |||
<section anchor="SEC11-uses-reorg" toc="exclude" numbered="true"> | ||||
</t> | <name>Reorganization of Sections 11.4 and 11.5 of RFC 5661</name> | |||
<t> | ||||
<section title="Re-organization of Sections 11.4 and 11.5 of RFC5661" | ||||
anchor="SEC11-uses-reorg" | ||||
toc="exclude"> | ||||
<t> | ||||
Previously, issues related to the fact that multiple location | Previously, issues related to the fact that multiple location | |||
entries directed the client to the same file system instance | entries directed the client to the same file system instance | |||
were dealt with | were dealt with in Section <xref target="RFC5661" sectionFormat="bare" se | |||
in a separate Section 11.5 of RFC5661 <xref target="RFC5661"/>. | ction="11.5"/> of RFC 5661 <xref target="RFC5661"/>. | |||
Because of the new treatment of | Because of the new treatment of trunking, these issues now belong | |||
trunking, these issues now belong within <xref target="SEC11-USES"/> | within <xref target="SEC11-USES" format="default"/>. | |||
below. | </t> | |||
</t> | <t> | |||
<t> | In this new section, trunking is covered in | |||
In this new section, | <xref target="SEC11-USES-trunk" format="default"/> together with the oth | |||
trunking is dealt with in | er uses | |||
<xref target="SEC11-USES-trunk"/> together with the other uses | ||||
of file system location information described in Sections | of file system location information described in Sections | |||
<xref target="SEC11-USES-types"/> through | <xref target="SEC11-USES-types" format="counter"/> through | |||
<xref target="SEC11-USES-ref" format="counter"/>. | <xref target="SEC11-USES-ref" format="counter"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
As a result, <xref target="SEC11-USES"/> which will replace | As a result, <xref target="SEC11-USES" format="default"/>, which replaces | |||
Section 11.4 of RFC5661 <xref target="RFC5661"/> is substantially | Section <xref target="RFC5661" sectionFormat="bare" section="11.4"/> | |||
different than the section it replaces in that some existing | of RFC 5661 <xref target="RFC5661"/>, is substantially | |||
sections will be replaced by corresponding sections below while, | different than the section it replaces in that some original | |||
at the same time, new sections will be added, resulting in | sections have been replaced by corresponding sections as described below, | |||
a replacement containing some renumbered sections, as follows: | while | |||
<list style ='symbols'> | new sections have been added: | |||
<t> | </t> | |||
The material in <xref target="SEC11-USES"/>, | <ul spacing="normal"> | |||
<li> | ||||
The material in <xref target="SEC11-USES" format="default"/>, | ||||
exclusive of subsections, replaces the material | exclusive of subsections, replaces the material | |||
in Section 11.4 of RFC5661 <xref target="RFC5661"/> exclusive of | in Section <xref target="RFC5661" sectionFormat="bare" section="11.4"/> of RFC 5661 <xref target="RFC5661"/> exclusive of | |||
subsections. | subsections. | |||
</t> | </li> | |||
<t> | <li> | |||
<xref target="SEC11-USES-mult"/> | <xref target="SEC11-USES-mult" format="default"/> | |||
is a new first subsection of the overall section. | is the new first subsection of the overall section. | |||
</li> | ||||
</t> | <li> | |||
<t> | <xref target="SEC11-USES-trunk" format="default"/> | |||
<xref target="SEC11-USES-trunk"/> | is the new second subsection of the overall section. | |||
is a new second subsection of the overall section. | </li> | |||
</t> | <li> | |||
<t> | ||||
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 | replaces (in order) one of the corresponding Sections | |||
the corresponding | <xref target="RFC5661" sectionFormat="bare" section="11.4.1"/>, | |||
Sections 11.4.1, 11.4.2, and 11.4.3 of | <xref target="RFC5661" sectionFormat="bare" section="11.4.2"/>, and | |||
RFC5661 <xref target="RFC5661"/>. | <xref target="RFC5661" sectionFormat="bare" section="11.4.3"/> of RFC | |||
11.4.4, and 11.4.5. | 5661 | |||
</t> | <xref target="RFC5661"/>. | |||
<t> | </li> | |||
<xref target="SEC11-USES-changes"/> | <li> | |||
is a new final subsection of the overall section. | <xref target="SEC11-USES-changes" format="default"/> | |||
</t> | is the new final subsection of the overall section. | |||
</list> | </li> | |||
</t> | </ul> | |||
</section> | </section> | |||
<section title="Re-organization of Material Dealing with File System Transit | <section anchor="SEC11-trans-reorg" toc="exclude" numbered="true"> | |||
ions" | <name>Reorganization of Material Dealing with File System Transitions< | |||
anchor="SEC11-trans-reorg" | /name> | |||
toc="exclude"> | <t> | |||
<t> | ||||
The material relating to file system transition, previously contained | The material relating to file system transition, previously contained | |||
in Section 11.7 of RFC5661 <xref target="RFC5661"/> has | in Section <xref target="RFC5661" sectionFormat="bare" section="11.7"/> o f RFC 5661 <xref target="RFC5661"/> has | |||
been reorganized and augmented as described below: | been reorganized and augmented as described below: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
Because there can be a shift of the network access paths used to | Because there can be a shift of the network access paths used to | |||
access a file system instance without any shift between replicas, | access a file system instance without any shift between replicas, | |||
a new <xref target="SEC11-trans-oview"/> distinguishes | a new <xref target="SEC11-trans-oview" format="default"/> distinguishes | |||
between those cases in which there is a shift between | between those cases in which there is a shift between | |||
distinct replicas and those involving a shift in network | distinct replicas and those involving a shift in network | |||
access paths | access paths with no shift between replicas. | |||
with no shift between replicas. | </t> | |||
<vspace blankLines="1"/> | <t> | |||
As a result, a new <xref target="SEC11-nwa"/> deals with network | As a result, the new <xref target="SEC11-nwa" format="default"/> deals | |||
address transitions while the bulk of the former Section 11.7 | with network | |||
(in RFC5661 <xref target="RFC5661"/>) | address transitions, while the bulk of the original Section | |||
is extensively modified as reflected in | <xref target="RFC5661" sectionFormat="bare" section="11.7"/> of RFC | |||
<xref target="SEC11-EFF"/> | 5661 <xref target="RFC5661"/> has been extensively modified as reflecte | |||
which is now limited to cases | d in | |||
<xref target="SEC11-EFF" format="default"/>, which is now limited to ca | ||||
ses | ||||
in which there is a shift between two different sets of replicas. | in which there is a shift between two different sets of replicas. | |||
</t> | ||||
</t> | </li> | |||
<t> | <li> | |||
The additional <xref target="SEC11-trans-locking"/> discusses the | The additional <xref target="SEC11-trans-locking" format="default"/> di | |||
scusses the | ||||
case in which a shift to a different replica is made and state | case in which a shift to a different replica is made and state | |||
is transferred to allow the client the ability to have continued | is transferred to allow the client the ability to have continued | |||
access to its accumulated locking state on the new server. | access to its accumulated locking state on the new server. | |||
</t> | </li> | |||
<t> | <li> | |||
The additional <xref target="SEC11-trans-client"/> discusses | The additional <xref target="SEC11-trans-client" format="default"/> dis | |||
the client's response to access transitions and how it determines | cusses | |||
the client's response to access transitions, how it determines | ||||
whether migration has occurred, and how it gets access to any | whether migration has occurred, and how it gets access to any | |||
transferred | transferred locking and session state. | |||
locking and session state. | </li> | |||
</t> | <li> | |||
<t> | The additional <xref target="SEC11-trans-server" format="default"/> dis | |||
The additional <xref target="SEC11-trans-server"/> discusses the | cusses the | |||
responsibilities of the source and destination servers when | responsibilities of the source and destination servers when | |||
transferring locking and session state. | transferring locking and session state. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | This reorganization has caused a renumbering of the sections | |||
This re-organization has caused a renumbering of the sections | within <xref target="RFC5661" sectionFormat="of" section="11"/> as descri | |||
within Section 11 of <xref target="RFC5661"/> as described below: | bed below: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The new Sections <xref target="SEC11-trans-oview" format="counter"/> | The new Sections <xref target="SEC11-trans-oview" format="counter"/> | |||
and <xref target="SEC11-nwa" format="counter"/> have resulted | and <xref target="SEC11-nwa" format="counter"/> have resulted | |||
in existing sections with these numbers to be renumbered. | in the renumbering of existing sections with these numbers. | |||
</t> | </li> | |||
<t> | <li> | |||
Section 11.7 of <xref target="RFC5661"/> will be substantially | <xref target="RFC5661" sectionFormat="of" section="11.7"/> has been sub | |||
modified and appear as | stantially | |||
<xref target="SEC11-EFF"/>. The necessary | modified and appears as <xref target="SEC11-EFF" format="default"/>. | |||
modifications reflect the fact that this section will only deal | The necessary | |||
with transitions between replicas while transitions between | modifications reflect the fact that this section only deals | |||
with transitions between replicas, while transitions between | ||||
network addresses are dealt with in other sections. Details | network addresses are dealt with in other sections. Details | |||
of the reorganization are described later in this section. | of the reorganization are described later in this section. | |||
</t> | </li> | |||
<t> | <li> | |||
The additional Sections | Sections | |||
<xref target="SEC11-trans-locking" format="counter"/>, | <xref target="SEC11-trans-locking" format="counter"/>, | |||
<xref target="SEC11-trans-client" format="counter"/>, and | <xref target="SEC11-trans-client" format="counter"/>, and | |||
<xref target="SEC11-trans-server" format="counter"/> have been | <xref target="SEC11-trans-server" format="counter"/> have been | |||
added. | added. | |||
</t> | </li> | |||
<t> | <li> | |||
Consequently, Sections 11.8, 11.9, 11.10, and 11.11 in | Consequently, Sections <xref target="RFC5661" sectionFormat="bare" sect | |||
<xref target="RFC5661"/> now appear | ion="11.8"/>, | |||
as Sections 11.13, 11.14, 11.15, and 11.16, | <xref target="RFC5661" sectionFormat="bare" section="11.9"/>, | |||
<xref target="RFC5661" sectionFormat="bare" section="11.10"/>, and | ||||
<xref target="RFC5661" sectionFormat="bare" section="11.11"/> in | ||||
<xref target="RFC5661" format="default"/> now appear | ||||
as Sections <xref target="effecting_referrals" format="counter"/>, | ||||
<xref target="fs_locations" format="counter"/>, | ||||
<xref target="SEC11-li-new" format="counter"/>, and | ||||
<xref target="fs_status" format="counter"/>, | ||||
respectively. | respectively. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | As part of this general reorganization, | |||
As part of this general re-organization, Section 11.7 of | Section <xref target="RFC5661" sectionFormat="bare" section="11.7"/> of | |||
RFC5661 <xref target="RFC5661"/> will be modified as described below: | RFC 5661 <xref target="RFC5661"/> | |||
<list style="symbols"> | has been modified as described below: | |||
<t> | </t> | |||
Sections 11.7 and 11.7.1 of RFC5661 <xref target="RFC5661"/> | <ul spacing="normal"> | |||
are to be | <li> | |||
replaced by Sections <xref target="SEC11-EFF" format="counter"/> | Sections <xref target="RFC5661" sectionFormat="bare" section="11.7"/> a | |||
and <xref target="SEC11-EFF-simul" format="counter"/>, respectively. | nd | |||
</t> | <xref target="RFC5661" sectionFormat="bare" section="11.7.1"/> of RFC | |||
<t> | 5661 <xref target="RFC5661" format="default"/> | |||
Section 11.7.2 (and included subsections) | have been replaced by Sections | |||
of RFC5661 <xref target="RFC5661"/> are to be deleted. | <xref target="SEC11-EFF" format="counter"/> and | |||
</t> | <xref target="SEC11-EFF-simul" format="counter"/>, respectively. | |||
<t> | </li> | |||
Sections 11.7.3, 11.7.4. 11.7.5, 11.7.5.1, and 11.7.6 | <li> | |||
of RFC5661 <xref target="RFC5661"/> are to be replaced by Sections | Section <xref target="RFC5661" sectionFormat="bare" section="11.7.2"/> | |||
of RFC 5661 (and included subsections) has been deleted. | ||||
</li> | ||||
<li> | ||||
Sections <xref target="RFC5661" sectionFormat="bare" section="11.7.3"/> | ||||
, | ||||
<xref target="RFC5661" sectionFormat="bare" section="11.7.4"/>, | ||||
<xref target="RFC5661" sectionFormat="bare" section="11.7.5"/>, | ||||
<xref target="RFC5661" sectionFormat="bare" section="11.7.5.1"/>, and | ||||
<xref target="RFC5661" sectionFormat="bare" section="11.7.6"/> of RFC | ||||
5661 | ||||
<xref target="RFC5661" format="default"/> have been replaced by Sectio | ||||
ns | ||||
<xref target="SEC11-EFF-fh" format="counter"/>, | <xref target="SEC11-EFF-fh" format="counter"/>, | |||
<xref target="SEC11-EFF-fileid" format="counter"/>, | <xref target="SEC11-EFF-fileid" format="counter"/>, | |||
<xref target="SEC11-EFF-fsid" format="counter"/>, | <xref target="SEC11-EFF-fsid" format="counter"/>, | |||
<xref target="SEC11-EFF-fsid-split" format="counter"/>, and | <xref target="SEC11-EFF-fsid-split" format="counter"/>, and | |||
<xref target="SEC11-EFF-change" format="counter"/> | <xref target="SEC11-EFF-change" format="counter"/> | |||
respectively in this document. | respectively in this document. | |||
</t> | </li> | |||
<t> | <li> | |||
Section 11.7.7 of RFC5661 <xref target="RFC5661"/> | Section <xref target="RFC5661" sectionFormat="bare" section="11.7.7"/> | |||
is to be replaced by | of RFC 5661 <xref target="RFC5661"/> has been replaced by | |||
<xref target="SEC11-EFF-lock"/> This sub-section has been | <xref target="SEC11-EFF-lock" format="default"/>. This subsection has | |||
moved to the end of the section dealing with file system | been | |||
transitions. | moved to the end of the section dealing with file system transitions. | |||
</t> | </li> | |||
<t> | <li> | |||
Sections 11.7.8, 11.7.9. and 11.7.10 of | Sections <xref target="RFC5661" sectionFormat="bare" section="11.7.8"/> | |||
RFC5661 <xref target="RFC5661"/> are to be replaced by Sections | , | |||
<xref target="RFC5661" sectionFormat="bare" section="11.7.9"/>, and | ||||
<xref target="RFC5661" sectionFormat="bare" section="11.7.10"/> of RFC | ||||
5661 | ||||
<xref target="RFC5661" format="default"/> have been replaced by Sectio | ||||
ns | ||||
<xref target="SEC11-EFF-wv" format="counter"/>, | <xref target="SEC11-EFF-wv" format="counter"/>, | |||
<xref target="SEC11-EFF-rdc" format="counter"/>, and | <xref target="SEC11-EFF-rdc" format="counter"/>, and | |||
<xref target="SEC11-EFF-data" format="counter"/> | <xref target="SEC11-EFF-data" format="counter"/> | |||
respectively in this document. | respectively in this document. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section anchor="SEC11-li-changes" toc="exclude" numbered="true"> | |||
<section title="Updates to treatment of fs_locations_info" | <name>Updates to the Treatment of fs_locations_info</name> | |||
anchor="SEC11-li-changes" | <t> | |||
toc="exclude"> | ||||
<t> | ||||
Various elements of the fs_locations_info attribute contain | Various elements of the fs_locations_info attribute contain | |||
information that applies to either a specific file system replica | information that applies to either a specific file system replica | |||
or to a network path or set of network paths used to access such | or to a network path or set of network paths used to access such a replic | |||
a replica. | a. | |||
The existing treatment of fs_locations info (in Section 11.10 of | The original treatment of fs_locations_info (Section <xref target="RFC566 | |||
RFC5661 <xref target="RFC5661"/>) does not clearly | 1" sectionFormat="bare" section="11.10"/> of RFC 5661 <xref target="RFC5661"/>) | |||
distinguish these cases, in | did not clearly distinguish these cases, in | |||
part because the document did not clearly distinguish replicas from | part because the document did not clearly distinguish replicas from | |||
the paths used to access them. | the paths used to access them. | |||
</t> | </t> | |||
<t> | <t> | |||
In addition, special clarification needed to be provided with regard | In addition, special clarification has been provided with regard | |||
to the following fields: | to the following fields: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
With regard to the handling of FSLI4GF_GOING, it needs to be | <li> | |||
made clear that this only applies to the unavailability of a | With regard to the handling of FSLI4GF_GOING, it was | |||
clarified that this only applies to the unavailability of a | ||||
replica rather than to a path to access a replica. | replica rather than to a path to access a replica. | |||
</t> | </li> | |||
<t> | <li> | |||
In describing the appropriate value for a server to use for | In describing the appropriate value for a server to use for | |||
fli_valid_for, it needs to be made clear that there is no | fli_valid_for, it was clarified that there is no | |||
need for the client to frequently fetch the fs_locations_info | need for the client to frequently fetch the fs_locations_info | |||
value to be prepared for shifts in trunking patterns. | value to be prepared for shifts in trunking patterns. | |||
</t> | </li> | |||
<t> | <li> | |||
Clarification of the rules for extensions to the fls_info needs | Clarification of the rules for extensions to the fls_info has | |||
to be provided. The existing treatment reflects the extension | been provided. The original treatment reflected the extension | |||
model in effect at the time RFC5661 <xref target="RFC5661"/> | model that was in effect at the time RFC 5661 <xref target="RFC5661" fo | |||
was written, | rmat="default"/> | |||
and needed to be updated in accordance with the extension model | was written, but has been updated in accordance with the extension mode | |||
described in RFC8178 <xref target="RFC8178"/>. | l | |||
</t> | described in RFC 8178 <xref target="RFC8178" format="default"/>. | |||
</list> | </li> | |||
</t> | </ul> | |||
</section> | </section> | |||
</section> | </section> | |||
<section title="Revisions Made to Operations in RFC5661" | <section anchor="CHG-ops" numbered="true" toc="default"> | |||
anchor="CHG-ops"> | <name>Revisions Made to Operations in RFC 5661</name> | |||
<t> | <t> | |||
Revised descriptions were needed to address issues that arose in | Descriptions have been revised to address issues that arose in | |||
effecting necessary changes to multi-server namespace features. | effecting necessary changes to multi-server namespace features. | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
The existing treatment of EXCHANGE_ID (in Section 18.35 of | <li> | |||
RFC5661 <xref target="RFC5661"/>) assumes that client IDs | The treatment of EXCHANGE_ID (Section <xref target="RFC5661" sectionForm | |||
cannot be created/ | at="bare" section="18.35"/> of RFC 5661 <xref target="RFC5661"/>) assumed that c | |||
confirmed other than by the EXCHANGE_ID and CREATE_SESSION | lient IDs | |||
cannot be created/confirmed other than by the EXCHANGE_ID and CREATE_SESS | ||||
ION | ||||
operations. Also, the necessary use of EXCHANGE_ID in recovery | operations. Also, the necessary use of EXCHANGE_ID in recovery | |||
from migration and related situations is not addressed clearly. | from migration and related situations was not clearly addressed. | |||
A revised treatment of EXCHANGE_ID is necessary and it appears in | A revised treatment of EXCHANGE_ID was necessary, and it appears in | |||
<xref target="OP_EXCHANGE_ID"/> while the specific differences | <xref target="OP_EXCHANGE_ID" format="default"/>, while the specific dif | |||
between it and the treatment within <xref target="RFC5661"/> | ferences | |||
are explained in <xref target="OTH-eid"/> below. | between it and the treatment within <xref target="RFC5661" format="defaul | |||
</t> | t"/> | |||
<t> | are explained in <xref target="OTH-eid" format="default"/> below. | |||
The existing treatment of RECLAIM_COMPLETE in section 18.51 of | </li> | |||
RFC5661 <xref target="RFC5661"/>) is not sufficiently clear about the | <li> | |||
purpose and use of the rca_one_fs and how the server is to deal | The treatment of RECLAIM_COMPLETE in Section <xref target="RFC5661" secti | |||
onFormat="bare" section="18.51"/> of RFC 5661 <xref target="RFC5661"/> was not s | ||||
ufficiently clear about the | ||||
purpose and use of the rca_one_fs and how the server was to deal | ||||
with inappropriate values of this argument. Because the | with inappropriate values of this argument. Because the | |||
resulting confusion raises interoperability issues, a new treatment | resulting confusion raised interoperability issues, a new treatment | |||
of RECLAIM_COMPLETE is necessary and it appears in | of RECLAIM_COMPLETE was necessary, and it appears in | |||
<xref target="OP_RECLAIM_COMPLETE"/> below while the specific differences | <xref target="OP_RECLAIM_COMPLETE" format="default"/>, while the specific | |||
between it and the treatment within RFC5661 <xref target="RFC5661"/> | differences | |||
are discussed in <xref target="OTH-rc"/> below. In addition, the | between it and the treatment within RFC 5661 <xref target="RFC5661" forma | |||
definitions of the reclaim-related errors receive an updated | t="default"/> | |||
treatment in <xref target="errors_reclaim"/> to reflect the fact | are discussed in <xref target="OTH-rc" format="default"/> below. In addi | |||
tion, the | ||||
definitions of the reclaim-related errors have received an updated | ||||
treatment in <xref target="errors_reclaim" format="default"/> to reflect | ||||
the fact | ||||
that there are multiple contexts for lock reclaim operations. | that there are multiple contexts for lock reclaim operations. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <section anchor="OTH-eid" toc="exclude" numbered="true"> | |||
<section title="Revision to Treatment of EXCHANGE_ID" | <name>Revision of Treatment of EXCHANGE_ID</name> | |||
anchor="OTH-eid" | <t> | |||
toc="exclude"> | There was a number of issues in the original treatment of | |||
EXCHANGE_ID in RFC 5661 <xref target="RFC5661" format="default"/> that ca | ||||
<t> | used problems | |||
There are a number of issues in the original treatment of | ||||
EXCHANGE_ID (in RFC5661 <xref target="RFC5661"/>) that cause problems | ||||
for Transparent State Migration and for the transfer of access | for Transparent State Migration and for the transfer of access | |||
between different network access paths | between different network access paths to the same file system instance. | |||
to the same file system instance. | </t> | |||
</t> | <t> | |||
<t> | These issues arose from the fact that this treatment was written: | |||
These issues arise from the fact that this treatment was | </t> | |||
written, | <ul spacing="normal"> | |||
<list style="symbols"> | <li> | |||
<t> | ||||
Assuming that a client ID can only become known to a server | Assuming that a client ID can only become known to a server | |||
by having been created by executing an EXCHANGE_ID, with | by having been created by executing an EXCHANGE_ID, with | |||
confirmation of the ID only possible by execution of a | confirmation of the ID only possible by execution of a | |||
CREATE_SESSION. | CREATE_SESSION. | |||
</t> | </li> | |||
<t> | <li> | |||
Considering the interactions between a client and a server only | Considering the interactions between a client and a server only | |||
occurring on a single network address | occurring on a single network address. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <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 | the treatment has been modified in several respects: | |||
several respects. | </t> | |||
<list style="symbols"> | <ul spacing="normal"> | |||
<t> | <li> | |||
It had been assumed that an | <t> | |||
EXCHANGED_ID executed when the server is already aware of a | It had been assumed that an EXCHANGE_ID executed when the server | |||
given client instance must be either updating associated | was already aware that a given client instance was either updating | |||
parameters (e.g. with respect to callbacks) or a lingering | associated parameters (e.g., with respect to callbacks) or dealing | |||
retransmission to deal with a previously lost reply. As | with a previously lost reply by retransmitting. As a | |||
result, any slot sequence returned by that operation | result, any slot sequence returned by that operation | |||
would be of no use. | would be of no use. The original treatment | |||
The existing treatment | went so far as to say that it "<bcp14>MUST NOT</bcp14>" be used, altho | |||
goes so far as to say that it "MUST NOT" be used, although | ugh | |||
this usage is not in accord with <xref target="RFC2119"/>. | this usage was not in accord with <xref target="RFC2119" format="defau | |||
This created | lt"/>. | |||
a difficulty when an EXCHANGE_ID is done after Transparent State | This created a difficulty when an EXCHANGE_ID is done after Transparen | |||
t 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. | |||
<vspace blankLines="1"/> | </t> | |||
<t> | ||||
In the updated treatment, CREATE_SESSION is a way that client | In the updated treatment, CREATE_SESSION is a way that client | |||
IDs are confirmed but it is understood that other ways are | IDs are confirmed, but it is understood that other ways are | |||
possible. The slot sequence can be used as needed and cases | possible. The slot sequence can be used as needed, and cases | |||
in which it would be of no use are appropriately noted. | in which it would be of no use are appropriately noted. | |||
</t> | </t> | |||
<t> | </li> | |||
It was assumed that the only functions of EXCHANGE_ID were to | <li> | |||
inform the server of the client, create the client ID, | <t> | |||
and communicate it to the client. When multiple | It had been assumed that the only functions of EXCHANGE_ID were to | |||
inform the server of the client, to create the client ID, | ||||
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. | |||
<vspace blankLines="1"/> | </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 | can be used by CREATE_SESSION and in associating a connection with an | |||
by CREATE_SESSION and in associating a connection with an | ||||
existing session. | existing session. | |||
</t> | </t> | |||
</li> | ||||
</list> | </ul> | |||
</t> | <t> | |||
<t> | The new treatment can be found in <xref target="OP_EXCHANGE_ID" format=" | |||
The new treatment can be found in <xref target="OP_EXCHANGE_ID"/> | default"/> | |||
above. | above. It supersedes the treatment in Section | |||
It supersedes the treatment in Section 18.35 of | <xref target="RFC5661" sectionFormat="bare" section="18.35"/> of RFC 566 | |||
RFC5661 <xref target="RFC5661"/>. | 1 <xref target="RFC5661"/>. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Revision to Treatment of RECLAIM_COMPLETE" | <section anchor="OTH-rc" toc="exclude" numbered="true"> | |||
anchor="OTH-rc" | <name>Revision of Treatment of RECLAIM_COMPLETE</name> | |||
toc="exclude"> | <t> | |||
<t> | ||||
The following changes were made to the treatment of | The following changes were made to the treatment of | |||
RECLAIM_COMPLETE in RFC5661 <xref target="RFC5661"/> to arrive at the | RECLAIM_COMPLETE in RFC 5661 <xref target="RFC5661" format="default"/> to | |||
treatment in <xref target="OP_RECLAIM_COMPLETE"/>. | arrive at the | |||
<list style="symbols"> | treatment in <xref target="OP_RECLAIM_COMPLETE" format="default"/>: | |||
<t> | </t> | |||
In a number of places the text is made more explicit about the | <ul spacing="normal"> | |||
<li> | ||||
In a number of places, the text was made more explicit about the | ||||
purpose of rca_one_fs and its connection to file system | purpose of rca_one_fs and its connection to file system | |||
migration. | migration. | |||
</t> | </li> | |||
<t> | <li> | |||
There is a discussion of situations in which particular forms of | There is a discussion of situations in which particular forms of | |||
RECLAIM_COMPLETE would need to be done. | RECLAIM_COMPLETE would need to be done. | |||
</t> | </li> | |||
<t> | <li> | |||
There is a discussion of interoperability issues that result | There is a discussion of interoperability issues between | |||
from implementations that may have arisen due to the lack of | implementations that may have arisen due to the lack of | |||
clarity of the previous treatment of RECLAIM_COMPLETE. | clarity of the previous treatment of RECLAIM_COMPLETE. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="CHG-errs" numbered="true" toc="default"> | |||
<name>Revisions Made to Error Definitions in RFC 5661</name> | ||||
<section title="Revisions Made to Error Definitions in RFC5661" | <t> | |||
anchor="CHG-errs"> | The new handling of various situations required revisions to | |||
<t> | some existing error definitions: | |||
The new handling of various situations required revisions of | </t> | |||
some existing error definition: | <ul spacing="normal"> | |||
<list style="symbols"> | <li> | |||
<t> | <t> | |||
Because of the need to appropriately address trunking-related | Because of the need to appropriately address trunking-related | |||
issues, some uses of the term "replica" in RFC5661 | issues, some uses of the term "replica" in RFC 5661 | |||
<xref target="RFC5661"/> | <xref target="RFC5661" format="default"/> | |||
have become problematic since a shift in network access paths was | became problematic because a shift in network access paths was | |||
considered to be a shift to a different replica. As a result, | considered to be a shift to a different replica. As a result, | |||
the existing definition of NFS4ERR_MOVED (in Section 15.1.2.4 of | the original definition of NFS4ERR_MOVED (in Section <xref target="RFC56 | |||
RFC5661 <xref target="RFC5661"/>) needs to be updated to reflect the | 61" sectionFormat="bare" section="15.1.2.4"/> of RFC 5661 <xref target="RFC5661" | |||
/>) was updated to reflect the | ||||
different handling of unavailability of a particular fs via a | different handling of unavailability of a particular fs via a | |||
specific network address. | specific network address. | |||
<vspace blankLines="1"/> | </t> | |||
<t> | ||||
Since such a situation is no longer | Since such a situation is no longer | |||
considered to constitute unavailability of a file system | considered to constitute unavailability of a file system | |||
instance, the description needs | instance, the description has been changed, even though the set of circu | |||
to change even though the set of circumstances in | mstances in | |||
which it is to be returned remain the same. | which it is to be returned remains the same. | |||
The new paragraph explicitly recognizes that a different network | The new paragraph explicitly recognizes that a different network | |||
address might be used, while the previous description, misleadingly, | address might be used, while the previous description, misleadingly, | |||
treated this as a shift between two replicas while only a single | treated this as a shift between two replicas while only a single | |||
file system instance might be involved. | file system instance might be involved. The updated description | |||
The updated description | appears in <xref target="err_MOVED" format="default"/>. | |||
appears in <xref target="err_MOVED"/> below. | </t> | |||
</t> | </li> | |||
<t> | <li> | |||
Because of the need to accommodate use of fs-specific grace periods, | Because of the need to accommodate the use of fs-specific grace periods, | |||
it is necessary to clarify some of the error definitions of | it was necessary to clarify some of the definitions of | |||
reclaim-related errors in Section 15 of RFC5661 | reclaim-related errors in Section | |||
<xref target="RFC5661"/>, | <xref target="RFC5661" sectionFormat="bare" section="15"/> of RFC 5661 | |||
so the text applies properly to reclaims for all types of grace | <xref target="RFC5661"/> | |||
periods. | so that the text applies properly to reclaims for all types of grace | |||
The updated descriptions | periods. The updated descriptions | |||
appear within <xref target="errors_reclaim"/> below. | appear within <xref target="errors_reclaim" format="default"/>. | |||
</t> | </li> | |||
<t> | <li> | |||
Because of the need to provide the clarifications in errata | Because of the need to provide the clarifications in errata | |||
report 2006 | report 2006 <xref target="Err2006" format="default"/> | |||
<xref target="Err2006"/> | ||||
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"/>. This | of NFS4ERR_DELAY appears in <xref target="err_DELAY" format="default"/>. | |||
errata report, unlike many other RFC5661 errata reports, is | This | |||
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. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | <section anchor="CHG-other" numbered="true" toc="default"> | |||
<section title="Other Revisions Made to RFC5661" | <name>Other Revisions Made to RFC 5661</name> | |||
anchor="CHG-other"> | <t> | |||
<t> | Besides the major reworking of Section <xref target="RFC5661" sectionForma | |||
Beside the major reworking of Section 11 and the associated revisions to | t="bare" section="11"/> of RFC 5661 <xref target="RFC5661"/> and the associated | |||
existing operations and errors, | revisions to | |||
there are a number of | existing operations and errors, there were a number of related changes tha | |||
related changes that are necessary: | t were necessary: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
The summary that appeared in Section 1.7.3.3 of | <li> | |||
RFC5661 <xref target="RFC5661"/> was revised to reflect the changes | The summary in Section <xref target="RFC5661" sectionFormat="bare" secti | |||
made in the revised <xref target="NEW11"/> above. | on="1.7.3.3"/> | |||
The updated summary | of RFC 5661 <xref target="RFC5661"/> was revised to reflect the changes | |||
appears as <xref target="PREP-intro"/> above. | made to | |||
</t> | <xref target="NEW11" format="default"/> above. The updated summary appe | |||
<t> | ars as | |||
The discussion of server scope which appeared in Section 2.10.4 of | <xref target="PREP-intro" format="default"/> above. | |||
RFC5661 <xref target="RFC5661"/> needed to be replaced, | </li> | |||
since the previous | <li> | |||
text appears to require a level of inter-server co-ordination | The discussion of server scope in Section | |||
<xref target="RFC5661" sectionFormat="bare" section="2.10.4"/> of RFC 56 | ||||
61 | ||||
<xref target="RFC5661"/> was replaced since it | ||||
appeared to require a level of inter-server coordination | ||||
incompatible with its basic function of avoiding the need for | incompatible with its basic function of avoiding the need for | |||
a globally uniform means of assigning server_owner values. | a globally uniform means of assigning server_owner values. | |||
A revised treatment appears in <xref target="Server_Scope"/>. | A revised treatment appears in <xref target="Server_Scope" format="defau | |||
</t> | lt"/>. | |||
<t> | </li> | |||
The discussion of trunking which appeared in Section 2.10.5 of | <li> | |||
RFC5661 <xref target="RFC5661"/> needed to be revised, to more clearly | The discussion of trunking in Section | |||
<xref target="RFC5661" sectionFormat="bare" section="2.10.5"/> of RFC 56 | ||||
61 <xref target="RFC5661"/> | ||||
was revised to more clearly | ||||
explain the multiple types of trunking support and how the | explain the multiple types of trunking support and how the | |||
client can be made aware of the existing trunking configuration. | client can be made aware of the existing trunking configuration. | |||
In addition, while the last paragraph (exclusive of sub-sections) of | In addition, while the last paragraph (exclusive of subsections) of | |||
that section, dealing with | that section dealing with server_owner changes was literally true, | |||
server_owner changes, is literally true, it has been a source | it had been a source of confusion. Since the original paragraph could b | |||
of confusion. Since the existing paragraph can be read as | e read as | |||
suggesting that such changes be dealt with non-disruptively, the | suggesting that such changes be handled nondisruptively, the | |||
issue needs to be clarified in the revised section, which appears | issue was clarified in the revised <xref target="Trunking" format="defau | |||
in <xref target="Trunking"/>. | lt"/>. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | </section> | |||
</section> | </section> | |||
</section> | <section anchor="SECBAD" numbered="true" toc="default"> | |||
<section title="Security Issues that Need to be Addressed" | <name>Security Issues That Need to Be Addressed</name> | |||
anchor="SECBAD"> | <t> | |||
<t> | ||||
The following issues in the treatment of security within the NFSv4.1 | The following issues in the treatment of security within the NFSv4.1 | |||
specification need to be addressed: | specification need to be addressed: | |||
<list style="symbols"> | ||||
<t> | ||||
The Security Considerations Section of RFC5661 <xref target="RFC5661" /> | ||||
is not written in accord with RFC3552 <xref target="RFC3552" /> | ||||
(also BCP72). Of particular concern is the fact that the section | ||||
does not | ||||
contain a threat analysis. | ||||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
The Security Considerations Section of RFC 5661 <xref target="RFC5661" fo | ||||
rmat="default"/> | ||||
was not written in accordance with RFC 3552 (BCP 72) <xref target="RFC355 | ||||
2" format="default"/>. | ||||
Of particular concern was the fact that the section | ||||
did not contain a threat analysis. | ||||
</li> | ||||
<li> | ||||
Initial analysis of the existing security issues with NFSv4.1 has made | Initial analysis of the existing security issues with NFSv4.1 has made | |||
it likely that a revised Security Considerations | it likely that a revised Security Considerations section for the | |||
Section for the | ||||
existing protocol (one containing a threat analysis) would be likely | existing protocol (one containing a threat analysis) would be likely | |||
to conclude that NFSv4.1 does not meet the goal of secure use on the | to conclude that NFSv4.1 does not meet the goal of secure use on the | |||
internet. | Internet. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | The Security Considerations section of | |||
The Security Considerations Section of | this document (<xref target="SECCON" format="default"/>) has not been thor | |||
this document (in <xref target="SECCON"/>) has not been thoroughly | oughly | |||
revised to correct the difficulties mentioned above. Instead, it has been | revised to correct the difficulties mentioned above. Instead, it has been | |||
modified to take proper account of issues related to the multi-server | modified to take proper account of issues related to the multi-server | |||
namespace features discussed in <xref target="NEW11"/>, leaving the | namespace features discussed in <xref target="NEW11" format="default"/>, l eaving the | |||
incomplete discussion and security weaknesses pretty much as they were. | incomplete discussion and security weaknesses pretty much as they were. | |||
</t> | </t> | |||
<t> | <t> | |||
The following major security issues need to be addressed in a | The following major security issues need to be addressed in a | |||
satisfactory fashion before an updated Security Considerations section | satisfactory fashion before an updated Security Considerations section | |||
can be published as part of a bis document for NFSv4.1: | can be published as part of a bis document for NFSv4.1: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li> | ||||
<t> | ||||
The continued use of AUTH_SYS and the security exposures it creates | The continued use of AUTH_SYS and the security exposures it creates | |||
needs to be addressed. Addressing this issue must not be limited to | need to be addressed. Addressing this issue must not be limited to | |||
the questions of whether the designation of this as OPTIONAL was | the questions of whether the designation of this as <bcp14>OPTIONAL</bcp1 | |||
4> was | ||||
justified and whether it should be changed. | justified and whether it should be changed. | |||
<vspace blankLines='1'/> | </t> | |||
In any event, it may not be possible, at this point, to correct the | <t> | |||
In any event, it may not be possible at this point to correct the | ||||
security problems created by continued use of AUTH_SYS simply by | security problems created by continued use of AUTH_SYS simply by | |||
revising this designation. | revising this designation. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
The lack of attention within the protocol to the possibility of | The lack of attention within the protocol to the possibility of | |||
pervasive monitoring attacks such as those described in RFC7258 | pervasive monitoring attacks such as those described in RFC 7258 | |||
<xref target="RFC7258"/> (also BCP188). | <xref target="RFC7258" format="default"/> (also BCP 188). | |||
<vspace blankLines='1'/> | </t> | |||
In that connection, the use | <t> | |||
of CREATE_SESSION without privacy protection needs to be addressed | In that connection, the use of CREATE_SESSION without privacy protection | |||
as it exposes the session ID to | needs to be addressed | |||
view by an attacker. This is worrisome as this is precisely the type | as it exposes the session ID to view by an attacker. This is worrisome a | |||
of protocol artifact alluded to in RFC7258, | s this is precisely the type | |||
of protocol artifact alluded to in RFC 7258, | ||||
which can enable further mischief on the part of | which can enable further mischief on the part of | |||
the attacker as it enables denial-of-service attacks which can be | the attacker as it enables denial-of-service attacks that can be | |||
executed effectively with only a single, normally low-value, | executed effectively with only a single, normally low-value, | |||
credential, even when RPCSEC_GSS authentication is in use. | credential, even when RPCSEC_GSS authentication is in use. | |||
</t> | </t> | |||
<t> | </li> | |||
<li> | ||||
<t> | ||||
The lack of effective use of privacy and integrity, even where the | The lack of effective use of privacy and integrity, even where the | |||
infrastructure to support use of RPCSEC_GSS in present, | infrastructure to support use of RPCSEC_GSS is present, | |||
needs to be addressed. | needs to be addressed. | |||
<vspace blankLines='1'/> | </t> | |||
<t> | ||||
In light of the security exposures that | In light of the security exposures that | |||
this situation creates, it is not enough to define a protocol that | this situation creates, it is not enough to define a protocol that | |||
could, with the provision of sufficient resources, address the problem. | could address this problem with the provision of sufficient resources. | |||
Instead, what is needed is a way to provide the necessary security, | Instead, what is needed is a way to provide the necessary security | |||
with very limited performance costs and without requiring | with very limited performance costs and without requiring | |||
security infrastructure that experience has shown is difficult for | security infrastructure, which experience has shown is difficult for | |||
many clients and servers to provide. | many clients and servers to provide. | |||
</t> | </t> | |||
</list> | </li> | |||
</t> | </ul> | |||
<t> | <t> | |||
In trying to provide a major security upgrade for a deployed protocol | In trying to provide a major security upgrade for a deployed protocol | |||
such as NFSv4.1, the working group, and the internet community is likely | such as NFSv4.1, the working group and the Internet community are likely | |||
to find itself dealing with a number of considerations such as the | to find themselves dealing with a number of considerations such as the | |||
following: | following: | |||
<list style="symbols"> | ||||
<t> | ||||
The need to accommodate existing deployments of existing protocols | ||||
as specified previously in existing Proposed Standards. | ||||
</t> | </t> | |||
<t> | <ul spacing="normal"> | |||
The difficulty of effecting changes to existing interoperating | <li> | |||
The need to accommodate existing deployments of protocols | ||||
specified previously in existing Proposed Standards. | ||||
</li> | ||||
<li> | ||||
The difficulty of effecting changes to existing, interoperating | ||||
implementations. | implementations. | |||
</t> | </li> | |||
<t> | <li> | |||
The difficulty of making changes to NFSv4 protocols other than those in | The difficulty of making changes to NFSv4 protocols other than those in | |||
the form of OPTIONAL extensions. | the form of <bcp14>OPTIONAL</bcp14> extensions. | |||
</t> | </li> | |||
<t> | <li> | |||
The tendency of those responsible for existing NFSv4 deployments to | The tendency of those responsible for existing NFSv4 deployments to | |||
ignore security flaws in the context of local area networks under | ignore security flaws in the context of local area networks under | |||
the mistaken | the mistaken impression that network isolation provides, in and of itself | |||
impression | , isolation from | |||
that network isolation provides, in and of itself, isolation from | ||||
all potential attackers. | all potential attackers. | |||
</t> | </li> | |||
</list> | </ul> | |||
</t> | <t> | |||
<t> | Given that the above-mentioned difficulties apply to minor | |||
Given that the difficulties mentioned above apply to minor | ||||
version zero as well, it may make sense to deal with these security issues | version zero as well, it may make sense to deal with these security issues | |||
in a common document applying to all NFSv4 minor versions. If | in a common document that applies to all NFSv4 minor versions. If | |||
that approach | that approach is taken, the Security Considerations section of an eventual | |||
is taken the, Security Considerations section of an eventual NFv4.1 bis | NFv4.1 bis | |||
document would reference that common document and the defining | document would reference that common document, and the defining | |||
RFCs for other minor versions might do so as well. | RFCs for other minor versions might do so as well. | |||
</t> | </t> | |||
</section> | ||||
</section> | <section numbered="false" toc="default"> | |||
<section title="Acknowledgments"> | <name>Acknowledgments</name> | |||
<section title="Acknowledgments for this Update" | <section toc="exclude" numbered="false"> | |||
toc="exclude"> | <name>Acknowledgments for This Update</name> | |||
<t> | <t> | |||
The authors wish to acknowledge the important role | The authors wish to acknowledge the important role | |||
of Andy Adamson of Netapp | of <contact fullname="Andy Adamson"/> of Netapp | |||
in clarifying the need for trunking discovery functionality, and | in clarifying the need for trunking discovery functionality, and | |||
exploring the role of the file system location attributes in | exploring the role of the file system location attributes in | |||
providing the | providing the | |||
necessary support. | necessary support. | |||
</t> | </t> | |||
<t> | <t> | |||
The authors wish to thank Tom Haynes of Hammerspace for drawing our | The authors wish to thank <contact fullname="Tom Haynes"/> of Hammerspace | |||
for drawing our | ||||
attention to the fact that internationalization and security might | attention to the fact that internationalization and security might | |||
best be handled in documents dealing with such protocol issues as they | best be handled in documents dealing with such protocol issues as they | |||
apply to all NFSv4 minor versions. | apply to all NFSv4 minor versions. | |||
</t> | </t> | |||
<t> | <t> | |||
The authors also wish to acknowledge the work of Xuan Qi of Oracle | The authors also wish to acknowledge the work of <contact fullname="Xuan | |||
with NFSv4.1 client and server prototypes of transparent state | Qi"/> of Oracle | |||
migration functionality. | with NFSv4.1 client and server prototypes of Transparent State | |||
</t> | Migration functionality. | |||
<t> | </t> | |||
<t> | ||||
The authors wish to thank others that brought attention to important | The authors wish to thank others that brought attention to important | |||
issues. The comments of Trond Myklebust of Primary Data related | issues. The comments of <contact fullname="Trond Myklebust"/> of Primary Data related | |||
to trunking helped to clarify the role of DNS in | to trunking helped to clarify the role of DNS in | |||
trunking discovery. Rick Macklem's comments brought attention to | trunking discovery. <contact fullname="Rick Macklem"/>'s comments broug ht attention to | |||
problems in the handling of the per-fs version of | problems in the handling of the per-fs version of | |||
RECLAIM_COMPLETE. | RECLAIM_COMPLETE. | |||
</t> | </t> | |||
<t> | <t> | |||
The authors wish to thank Olga Kornievskaia of Netapp for her helpful | The authors wish to thank <contact fullname="Olga Kornievskaia"/> of Net | |||
app for her helpful | ||||
review comments. | review comments. | |||
</t> | </t> | |||
</section> | </section> | |||
<section title="Acknowledgments for RFC5661" | <section toc="exclude" numbered="false"> | |||
toc="exclude"> | <name>Acknowledgments for RFC 5661</name> | |||
<t> | ||||
<t> | ||||
The initial text for the SECINFO extensions were edited by | The initial text for the SECINFO extensions were edited by | |||
Mike Eisler with contributions from Peng Dai, Sergey Klyushin, and | <contact fullname="Mike Eisler"/> with contributions from <contact fullnam | |||
Carl Burnett. | e="Peng Dai"/>, <contact fullname="Sergey Klyushin"/>, and | |||
</t> | <contact fullname="Carl Burnett"/>. | |||
<t> | </t> | |||
<t> | ||||
The initial text for the SESSIONS extensions were edited by | The initial text for the SESSIONS extensions were edited by | |||
Tom Talpey, Spencer Shepler, Jon Bauman with contributions from | <contact fullname="Tom Talpey"/>, <contact fullname="Spencer Shepler"/>, | |||
Charles Antonelli, Brent Callaghan, Mike Eisler, John Howard, Chet | <contact fullname="Jon Bauman"/> with contributions from | |||
Juszczak, Trond Myklebust, Dave Noveck, John Scott, Mike | <contact fullname="Charles Antonelli"/>, <contact fullname="Brent Ca | |||
Stolarchuk, and Mark Wittle. | llaghan"/>, <contact fullname="Mike Eisler"/>, <contact fullname="John How | |||
</t> | ard"/>, <contact fullname="Chet Juszczak"/>, <contact fullname="Trond Mykl | |||
<t> | ebust"/>, <contact fullname="Dave Noveck"/>, <contact fullname="John Scott | |||
"/>, <contact fullname="Mike Stolarchuk"/>, and <contact fullname="Mark Wittle"/ | ||||
>. | ||||
</t> | ||||
<t> | ||||
Initial text relating to multi-server namespace features, | Initial text relating to multi-server namespace features, | |||
including the concept of referrals, were contributed by | including the concept of referrals, were contributed by | |||
Dave Noveck, Carl Burnett, and Charles Fan with contributions | <contact fullname="Dave Noveck"/>, <contact fullname="Carl Burnett"/>, | |||
from Ted Anderson, Neil Brown, and Jon Haswell. | and <contact fullname="Charles Fan"/> with contributions | |||
</t> | from <contact fullname="Ted Anderson"/>, <contact fullname="Neil Bro | |||
<t> | wn"/>, and <contact fullname="Jon Haswell"/>. | |||
</t> | ||||
<t> | ||||
The initial text for the Directory Delegations support were | The initial text for the Directory Delegations support were | |||
contributed by Saadia Khan with input from Dave Noveck, Mike | contributed by <contact fullname="Saadia Khan"/> with input from | |||
Eisler, Carl Burnett, Ted Anderson, and Tom Talpey. | <contact fullname="Dave Noveck"/>, <contact fullname="Mike Eisler"/>, | |||
</t> | <contact fullname="Carl Burnett"/>, <contact fullname="Ted Anderson"/>, | |||
<t> | and <contact fullname="Tom Talpey"/>. | |||
</t> | ||||
<t> | ||||
The initial text for the ACL explanations were contributed by | The initial text for the ACL explanations were contributed by | |||
Sam Falkner and Lisa Week. | <contact fullname="Sam Falkner"/> and <contact fullname="Lisa Week"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
The pNFS work was inspired by the NASD and OSD | The pNFS work was inspired by the NASD and OSD | |||
work done by Garth Gibson. Gary Grider has also | work done by <contact fullname="Garth Gibson"/>. <contact fullname="Gary Grider"/> has also | |||
been a champion of high-performance parallel I/O. | been a champion of high-performance parallel I/O. | |||
Garth Gibson and Peter Corbett started the pNFS | <contact fullname="Garth Gibson"/> and <contact fullname="Peter Corbett"/> started the pNFS | |||
effort with a problem statement document for the IETF | effort with a problem statement document for the IETF | |||
that formed the basis for the pNFS work in NFSv4.1. | that formed the basis for the pNFS work in NFSv4.1. | |||
</t> | </t> | |||
<t> | <t> | |||
The initial text for the parallel NFS support was edited by | The initial text for the parallel NFS support was edited by | |||
Brent Welch and Garth Goodson. Additional authors for those | <contact fullname="Brent Welch"/> and <contact fullname="Garth Goodson"/>. | |||
documents were Benny Halevy, David Black, and Andy Adamson. | Additional authors for those | |||
documents were <contact fullname="Benny Halevy"/>, <contact fullname="Davi | ||||
d Black"/>, and <contact fullname="Andy Adamson"/>. | ||||
Additional input came from the informal group that contributed | Additional input came from the informal group that contributed | |||
to the construction of the initial pNFS drafts; specific | to the construction of the initial pNFS drafts; specific | |||
acknowledgment goes to Gary Grider, Peter Corbett, Dave Noveck, | acknowledgment goes to <contact fullname="Gary Grider"/>, <contact fullnam | |||
Peter Honeyman, and Stephen Fridella. | e="Peter Corbett"/>, <contact fullname="Dave Noveck"/>, | |||
</t> | <contact fullname="Peter Honeyman"/>, and <contact fullname="Stephen Fride | |||
<t> | lla"/>. | |||
Fredric Isaman found several errors in draft versions of the | </t> | |||
<t> | ||||
<contact fullname="Fredric Isaman"/> found several errors in draft version | ||||
s of the | ||||
ONC RPC XDR description of the NFSv4.1 protocol. | ONC RPC XDR description of the NFSv4.1 protocol. | |||
</t> | </t> | |||
<t> | <t> | |||
Audrey Van Belleghem provided, in numerous ways, essential | <contact fullname="Audrey Van Belleghem"/> provided, in numerous ways, ess | |||
co-ordination and management of the process of editing the | ential | |||
coordination and management of the process of editing the | ||||
specification documents. | specification documents. | |||
</t> | </t> | |||
<t> | <t> | |||
Richard Jernigan gave feedback on the file layout's striping | <contact fullname="Richard Jernigan"/> gave feedback on the file layout's | |||
striping | ||||
pattern design. | pattern design. | |||
</t> | </t> | |||
<t> | <t> | |||
Several formal inspection teams were formed to review various | Several formal inspection teams were formed to review various | |||
areas of the protocol. All the inspections found significant | areas of the protocol. All the inspections found significant | |||
errors and room for improvement. NFSv4.1's inspection teams | errors and room for improvement. NFSv4.1's inspection teams | |||
were: | were: | |||
<list style="symbols"> | </t> | |||
<t> | <ul spacing="normal"> | |||
<li><t> | ||||
ACLs, with the following inspectors: | ACLs, with the following inspectors: | |||
Sam Falkner, | <contact fullname="Sam Falkner"/>, | |||
Bruce Fields, | <contact fullname="Bruce Fields"/>, | |||
Rahul Iyer, | <contact fullname="Rahul Iyer"/>, | |||
Saadia Khan, | <contact fullname="Saadia Khan"/>, | |||
Dave Noveck, | <contact fullname="Dave Noveck"/>, | |||
Lisa Week, | <contact fullname="Lisa Week"/>, | |||
Mario Wurzl, | <contact fullname="Mario Wurzl"/>, | |||
and | and | |||
<contact fullname="Alan Yoder"/>.</t> | ||||
Alan Yoder. | </li> | |||
<li><t> | ||||
</t> | ||||
<t> | ||||
Sessions, with the following inspectors: | Sessions, with the following inspectors: | |||
William Brown, | <contact fullname="William Brown"/>, | |||
Tom Doeppner, | <contact fullname="Tom Doeppner"/>, | |||
Robert Gordon, | <contact fullname="Robert Gordon"/>, | |||
Benny Halevy, | <contact fullname="Benny Halevy"/>, | |||
Fredric Isaman, | <contact fullname="Fredric Isaman"/>, | |||
Rick Macklem, | <contact fullname="Rick Macklem"/>, | |||
Trond Myklebust, | <contact fullname="Trond Myklebust"/>, | |||
Dave Noveck, | <contact fullname="Dave Noveck"/>, | |||
Karen Rochford, | <contact fullname="Karen Rochford"/>, | |||
John Scott, | <contact fullname="John Scott"/>, | |||
and | and | |||
<contact fullname="Peter Shah"/>.</t> | ||||
Peter Shah. | </li> | |||
<li><t> | ||||
</t> | ||||
<t> | ||||
Initial pNFS inspection, with the following inspectors: | Initial pNFS inspection, with the following inspectors: | |||
Andy Adamson, | <contact fullname="Andy Adamson"/>, | |||
David Black, | <contact fullname="David Black"/>, | |||
Mike Eisler, | <contact fullname="Mike Eisler"/>, | |||
Marc Eshel, | <contact fullname="Marc Eshel"/>, | |||
Sam Falkner, | <contact fullname="Sam Falkner"/>, | |||
Garth Goodson, | <contact fullname="Garth Goodson"/>, | |||
Benny Halevy, | <contact fullname="Benny Halevy"/>, | |||
Rahul Iyer, | <contact fullname="Rahul Iyer"/>, | |||
Trond Myklebust, | <contact fullname="Trond Myklebust"/>, | |||
Spencer Shepler, | <contact fullname="Spencer Shepler"/>, | |||
and | and | |||
<contact fullname="Lisa Week"/>.</t> | ||||
Lisa Week. | </li> | |||
<li><t> | ||||
</t> | ||||
<t> | ||||
Global namespace, with the following inspectors: | Global namespace, with the following inspectors: | |||
Mike Eisler, | <contact fullname="Mike Eisler"/>, | |||
Dan Ellard, | <contact fullname="Dan Ellard"/>, | |||
Craig Everhart, | <contact fullname="Craig Everhart"/>, | |||
Fredric Isaman, | <contact fullname="Fredric Isaman"/>, | |||
Trond Myklebust, | <contact fullname="Trond Myklebust"/>, | |||
Dave Noveck, | <contact fullname="Dave Noveck"/>, | |||
Theresa Raj, | <contact fullname="Theresa Raj"/>, | |||
Spencer Shepler, | <contact fullname="Spencer Shepler"/>, | |||
Renu Tewari, | <contact fullname="Renu Tewari"/>, | |||
and | ||||
and | <contact fullname="Robert Thurlow"/>.</t> | |||
</li> | ||||
Robert Thurlow. | <li><t> | |||
</t> | ||||
<t> | ||||
NFSv4.1 file layout type, with the following inspectors: | NFSv4.1 file layout type, with the following inspectors: | |||
Andy Adamson, | <contact fullname="Andy Adamson"/>, | |||
Marc Eshel, | <contact fullname="Marc Eshel"/>, | |||
Sam Falkner, | <contact fullname="Sam Falkner"/>, | |||
Garth Goodson, | <contact fullname="Garth Goodson"/>, | |||
Rahul Iyer, | <contact fullname="Rahul Iyer"/>, | |||
Trond Myklebust, | <contact fullname="Trond Myklebust"/>, | |||
and | and | |||
Lisa Week. | <contact fullname="Lisa Week"/>.</t> | |||
</t> | </li> | |||
<li><t> | ||||
<t> | ||||
NFSv4.1 locking and directory delegations, with the following inspectors: | NFSv4.1 locking and directory delegations, with the following inspectors: | |||
Mike Eisler, | <contact fullname="Mike Eisler"/>, | |||
Pranoop Erasani, | <contact fullname="Pranoop Erasani"/>, | |||
Robert Gordon, | <contact fullname="Robert Gordon"/>, | |||
Saadia Khan, | <contact fullname="Saadia Khan"/>, | |||
Eric Kustarz, | <contact fullname="Eric Kustarz"/>, | |||
Dave Noveck, | <contact fullname="Dave Noveck"/>, | |||
Spencer Shepler, | <contact fullname="Spencer Shepler"/>, | |||
and | and | |||
Amy Weaver. | <contact fullname="Amy Weaver"/>.</t> | |||
</t> | </li> | |||
<li><t> | ||||
<t> | ||||
EXCHANGE_ID and DESTROY_CLIENTID, with the following inspectors: | EXCHANGE_ID and DESTROY_CLIENTID, with the following inspectors: | |||
Mike Eisler, | <contact fullname="Mike Eisler"/>, | |||
Pranoop Erasani, | <contact fullname="Pranoop Erasani"/>, | |||
Robert Gordon, | <contact fullname="Robert Gordon"/>, | |||
Benny Halevy, | <contact fullname="Benny Halevy"/>, | |||
Fredric Isaman, | <contact fullname="Fredric Isaman"/>, | |||
Saadia Khan, | <contact fullname="Saadia Khan"/>, | |||
Ricardo Labiaga, | <contact fullname="Ricardo Labiaga"/>, | |||
Rick Macklem, | <contact fullname="Rick Macklem"/>, | |||
Trond Myklebust, | <contact fullname="Trond Myklebust"/>, | |||
Spencer Shepler, | <contact fullname="Spencer Shepler"/>, | |||
and | and | |||
<contact fullname="Brent Welch"/>.</t> | ||||
</li> | ||||
Brent Welch. | <li><t> | |||
</t> | ||||
<t> | ||||
Final pNFS inspection, with the following inspectors: | Final pNFS inspection, with the following inspectors: | |||
Andy Adamson, | <contact fullname="Andy Adamson"/>, | |||
Mike Eisler, | <contact fullname="Mike Eisler"/>, | |||
Mark Eshel, | <contact fullname="Mark Eshel"/>, | |||
Sam Falkner, | <contact fullname="Sam Falkner"/>, | |||
Jason Glasgow, | <contact fullname="Jason Glasgow"/>, | |||
Garth Goodson, | <contact fullname="Garth Goodson"/>, | |||
Robert Gordon, | <contact fullname="Robert Gordon"/>, | |||
Benny Halevy, | <contact fullname="Benny Halevy"/>, | |||
Dean Hildebrand, | <contact fullname="Dean Hildebrand"/>, | |||
Rahul Iyer, | <contact fullname="Rahul Iyer"/>, | |||
Suchit Kaura, | <contact fullname="Suchit Kaura"/>, | |||
Trond Myklebust, | <contact fullname="Trond Myklebust"/>, | |||
Anatoly Pinchuk, | <contact fullname="Anatoly Pinchuk"/>, | |||
Spencer Shepler, | <contact fullname="Spencer Shepler"/>, | |||
Renu Tewari, | <contact fullname="Renu Tewari"/>, | |||
Lisa Week, | <contact fullname="Lisa Week"/>, | |||
and | and | |||
<contact fullname="Brent Welch"/>.</t> | ||||
Brent Welch. | </li> | |||
</ul> | ||||
</t> | <t> | |||
</list> | ||||
</t> | ||||
<t> | ||||
A review team worked together to generate the tables of assignments of | A review team worked together to generate the tables of assignments of | |||
error sets to operations and make sure that each such assignment had | error sets to operations and make sure that each such assignment had | |||
two or more people validating it. Participating in the process were | two or more people validating it. Participating in the process were | |||
Andy Adamson, | <contact fullname="Andy Adamson"/>, | |||
Mike Eisler, | <contact fullname="Mike Eisler"/>, | |||
Sam Falkner, | <contact fullname="Sam Falkner"/>, | |||
Garth Goodson, | <contact fullname="Garth Goodson"/>, | |||
Robert Gordon, | <contact fullname="Robert Gordon"/>, | |||
Trond Myklebust, | <contact fullname="Trond Myklebust"/>, | |||
Dave Noveck, | <contact fullname="Dave Noveck"/>, | |||
Spencer Shepler, | <contact fullname="Spencer Shepler"/>, | |||
Tom Talpey, | <contact fullname="Tom Talpey"/>, | |||
Amy Weaver, | <contact fullname="Amy Weaver"/>, | |||
and | and | |||
Lisa Week. | <contact fullname="Lisa Week"/>. | |||
</t> | </t> | |||
<t> | <t> | |||
Jari Arkko, David Black, Scott Bradner, Lisa | <contact fullname="Jari Arkko"/>, <contact fullname="David Black"/>, | |||
Dusseault, Lars Eggert, Chris Newman, and Tim | <contact fullname="Scott Bradner"/>, <contact fullname="Lisa Dusseault"/ | |||
Polk provided valuable review and guidance. | >, <contact fullname="Lars Eggert"/>, <contact fullname="Chris Newman"/>, an | |||
d <contact fullname="Tim Polk"/> provided valuable review and guidance. | ||||
</t> | ||||
<t> | ||||
Olga Kornievskaia found several errors in the SSV specification. | ||||
</t> | ||||
<t> | </t> | |||
Ricardo Labiaga found several places where the use of RPCSEC_GSS | <t> | |||
<contact fullname="Olga Kornievskaia"/> found several errors in the SSV speci | ||||
fication. | ||||
</t> | ||||
<t> | ||||
<contact fullname="Ricardo Labiaga"/> found several places where the use of R | ||||
PCSEC_GSS | ||||
was underspecified. | was underspecified. | |||
</t> | </t> | |||
<t> | ||||
<t> | ||||
Those who provided miscellaneous comments include: | Those who provided miscellaneous comments include: | |||
Andy Adamson, Sunil Bhargo, Alex Burlyga, Pranoop Erasani, | <contact fullname="Andy Adamson"/>, <contact fullname="Sunil Bhargo"/>, | |||
Bruce Fields, Vadim Finkelstein, Jason Goldschmidt, Vijay | <contact fullname="Alex Burlyga"/>, <contact fullname="Pranoop Erasani"/>, | |||
K. Gurbani, Sergey Klyushin, Ricardo Labiaga, James Lentini, Anshul | <contact fullname="Bruce Fields"/>, <contact fullname="Vadim Finkelstein"/ | |||
Madan, Daniel Muntz, Daniel Picken, Archana Ramani, Jim Rees, Mahesh | >, <contact fullname="Jason Goldschmidt"/>, <contact fullname="Vijay K. Gurba | |||
Siddheshwar, Tom Talpey, and Peter Varga. | ni"/>, <contact fullname="Sergey Klyushin"/>, <contact fullname="Ricardo Labiaga | |||
"/>, <contact fullname="James Lentini"/>, <contact fullname="Anshul Madan"/>, | ||||
</t> | <contact fullname="Daniel Muntz"/>, <contact fullname="Daniel Picken"/>, <co | |||
ntact fullname="Archana Ramani"/>, <contact fullname="Jim Rees"/>, <contact f | ||||
</section> | ullname="Mahesh Siddheshwar"/>, <contact fullname="Tom Talpey"/>, and <contac | |||
</section> | t fullname="Peter Varga"/>. | |||
</back> | ||||
</t> | ||||
</section> | ||||
</section> | ||||
</back> | ||||
</rfc> | </rfc> | |||
End of changes. 5934 change blocks. | ||||
21265 lines changed or deleted | 20627 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/ |