1 - 3 - 6 - A - B - C - D - E - F - G - H - I - K - L - M - N - O - P - Q - R - S - T - U - V - W - X
client
Click on the red underlined text to get to the source
... state model has added an open_owner4 identifier. This was
done to accommodate Posix based clients and the model they use for
file locking. For Posix clients, an open_owner4 would correspond
...
... done to accommodate Posix based clients and the model they use for
file locking. For Posix clients, an open_owner4 would correspond
to a file descriptor potentially shared amongst a set of processes
and the lock_owner4 identifier ...
... their size.
o Added the mounted_on_filed attribute to allow Posix clients to
correctly construct local mounts.
...
... o Modified the SETCLIENTID/SETCLIENTID_CONFIRM operations to deal
correctly with confirmation details along with adding the ability
to specify new client callback information. Also added
clarification of the callback information itself.
...
...
o Added a new operation LOCKOWNER_RELEASE to enable notifying the
server that a lock_owner4 will no longer be used by the client.
o RENEW operation changes to identify the client ...
... by the client.
o RENEW operation changes to identify the client correctly and allow
for additional error returns.
...
... data type from LOOKUP and OPEN in
favor of having the client construct a sequence of LOOKUP
operations to achieive the same effect.
...
... latency is high and bandwidth is low, and scale to very
large numbers of clients per server.
o Strong security ...
... GSS protocol. Additionally, the NFS version
4 protocol provides a mechanism to allow clients and servers the
ability to negotiate security and require clients and servers ...
... clients and servers the
ability to negotiate security and require clients and servers to
support a minimal set of security schemes.
...
... NFS version 4 protocol
has added a new operation which provides the client a method of
querying the server about its policies regarding which security
mechanisms ...
... querying the server about its policies regarding which security
mechanisms must be used for access to the server's filesystem
resources. With this, the client can securely match the security
mechanism that meets the policies specified at both the client and
server.
...
... resources. With this, the client can securely match the security
mechanism that meets the policies specified at both the client and
server.
...
... NFS procedures.
With the use of the COMPOUND procedure, the client is able to build
simple or complex requests. These COMPOUND requests allow for a
reduction in the number of RPCs needed for logical filesystem
...
... reduction in the number of RPCs needed for logical filesystem
operations. For example, without previous contact with a server a
client will be able to read data from a file in one request by
combining LOOKUP, OPEN, and READ operations in a single COMPOUND RPC ...
... by the server. Once an operation
returns a failing result, the evaluation ends and the results of all
evaluated operations are returned to the client.
The NFS ...
... The NFS version 4 protocol continues to have the client refer to a
file or directory at the server by a "filehandle". The COMPOUND
procedure has a method ...
... persistent and volatile filehandle types, the server implementation
can match the abilities of the filesystem at the server along with
the operating environment. The client will have knowledge of the
type of filehandle being provided by the server and can be prepared
...
... for the filesystem and file objects were a fixed set of mainly UNIX
attributes. If the server or client did not support a particular
attribute, it would have to simulate the attribute the best it could.
...
... stream that is associated with a
directory or file and referred to by a string name. Named attributes
are meant to be used by client applications as a method to associate
application specific data with a regular file or directory.
...
... replicate server filesystems is enabled within the protocol. The
filesystem locations attribute provides a method for the client to
probe the server about the location of a filesystem. In the event of
...
... probe the server about the location of a filesystem. In the event of
a migration of a filesystem, the client will receive an error when
operating on the filesystem and it can then query as to the new file
system ...
... query as to the new file
system location. Similar steps are used for replication, the client
is able to query the server for the multiple available locations of a
...
... is able to query the server for the multiple available locations of a
particular filesystem. From this information, the client can use its
own policies to access the appropriate filesystem location.
...
... state held by a NFS
client. If the client does not renew its lease within the defined
period, all state ...
... NFS
client. If the client does not renew its lease within the defined
period, all state associated with the client ...
... client does not renew its lease within the defined
period, all state associated with the client's lease may be released
by the server. The client ...
... client's lease may be released
by the server. The client may renew its lease with use of the RENEW
operation or implicitly by use of other operations (primarily READ).
...
... Client Caching and Delegation ...
... protocol is similar to previous versions. Attributes and directory
information are cached for a duration determined by the client. At
the end of a predefined timeout, the client will query ...
... information are cached for a duration determined by the client. At
the end of a predefined timeout, the client will query the server to
see if the related filesystem object has been updated.
...
... see if the related filesystem object has been updated.
For file data, the client checks its cache validity when the file is
...
... opened. A query is sent to the server to determine if the file has
been changed. Based on this information, the client determines if
the data cache for the file should kept or released. Also, when the
...
... version 4 in the area of caching is the
ability of the server to delegate certain responsibilities to the
client. When the server grants a delegation for a file to a client,
...
... client. When the server grants a delegation for a file to a client,
the client is guaranteed certain semantics ...
... delegation for a file to a client,
the client is guaranteed certain semantics with respect to the
sharing of that file with other clients ...
... client is guaranteed certain semantics with respect to the
sharing of that file with other clients. At OPEN, the server may
provide the client either a read or write delegation ...
... sharing of that file with other clients. At OPEN, the server may
provide the client either a read or write delegation for the file.
If the client ...
... client either a read or write delegation for the file.
If the client is granted a read delegation, it is assured that no
other client ...
... client is granted a read delegation, it is assured that no
other client has the ability to write to the file for the duration of
the delegation. If the client ...
... client has the ability to write to the file for the duration of
the delegation. If the client is granted a write delegation, the
client ...
... client is granted a write delegation, the
client is assured that no other client has read or write access to
the file.
...
... delegation, the
client is assured that no other client has read or write access to
the file.
...
... Delegations can be recalled by the server. If another client
requests access to the file in such a way that the access conflicts
with the granted delegation, the server is able to notify the initial
...
... with the granted delegation, the server is able to notify the initial
client and recall the delegation. This requires that a callback path
exist between the server and client ...
... client and recall the delegation. This requires that a callback path
exist between the server and client. If this callback path does not
exist, then delegations can not be granted. The essence of a
...
... delegations can not be granted. The essence of a
delegation is that it allows the client to locally service operations
such as OPEN, CLOSE, LOCK, LOCKU, READ, WRITE without immediate
...
... entity that accesses the NFS server's
resources. The client may be an application which contains
the logic to access the NFS server directly. The client ...
... client may be an application which contains
the logic to access the NFS server directly. The client
may also be the traditional operating system client ...
... client
may also be the traditional operating system client remote
filesystem services for a set of applications.
...
... services for a set of applications.
In the case of file locking the client is the entity that
maintains a set of locks on behalf of one or more
...
... entity that
maintains a set of locks on behalf of one or more
applications. This client is responsible for crash or
failure recovery for those locks it manages.
...
... failure recovery for those locks it manages.
Note that multiple clients may share the same transport and
multiple clients ...
... clients may share the same transport and
multiple clients may exist on the same network node.
...
... Clientid A 64-bit quantity used as a unique, short-hand reference to
a client supplied Verifier and ID. The server is
responsible for supplying the Clientid.
...
... Lease An interval of time defined by the server for which the
client is irrevocably granted a lock. At the end of a
lease period the lock may be revoked if the lease has not
been extended. The lock must be revoked if a conflicting
...
... Server The "Server" is the entity responsible for coordinating
client access to a set of filesystems.
Stable Storage
...
... Verifier A 64-bit quantity generated by the client that the server
can use to determine if the client has restarted and lost
...
... 64-bit quantity generated by the client that the server
can use to determine if the client has restarted and lost
all previous lock state.
...
... timestamps stored for a filesystem object is less than
defined, loss of precision can occur. An adjunct time maintenance
protocol is recommended to reduce client and server time skew.
time_how4
...
... LINK, REMOVE, RENAME
operations to let the client know the value of the change attribute
for the directory in which the target filesystem object resides.
...
... The clientaddr4 structure is used as part of the SETCLIENTID
operation to either specify the address of the client that is using a
clientid or as part of the callback registration. The
...
... };
This structure is used by the client to inform the server of its call
back address; includes the program number and client ...
... by the client to inform the server of its call
back address; includes the program number and client address.
...
... This structure is used for the various state sharing mechanisms
between the client and server. For the client, this data structure
...
... state sharing mechanisms
between the client and server. For the client, this data structure
is read-only. The starting ...
... starting value of the seqid field is undefined.
The server is required to increment the seqid field monotonically at
each transition of the stateid. This is important since the client
will inspect the seqid in OPEN stateids to determine the order of
OPEN processing done by the server ...
... If TCP is used as the transport, the client and server SHOULD use
persistent connections. This will prevent the weakening of TCP ...
... model. In particular, NFS over TCP client implementations have
traditionally multiplexed traffic for multiple users over a common
...
... TCP connection between an NFS client and server. This has been true,
regardless whether the NFS client ...
... client and server. This has been true,
regardless whether the NFS client is using AUTH_SYS, AUTH_DH ...
... TCP connection management in proportion to the
number of expected client machines. It is intended that NFS version
4 will not modify this connection ...
... NFS version 4
clients that violate this assumption can expect scaling issues on the
server and hence reduced service.
...
...
Note that for various timers, the client and server should avoid
inadvertent synchronization of those timers ...
... Client Retransmission Behavior ...
... contract between NFS version 4 clients and servers, clients MUST NOT
retry a request unless one or both of the following are true:
...
... NFS version 4 clients and servers, clients MUST NOT
retry a request unless one or both of the following are true:
...
... connection to see if has been broken.
Use of the NULL procedure is one recommended way to do so. So, when
a client experiences a remote procedure call timeout (of some
arbitrary implementation specific amount), rather than retrying the
...
... break will eventually be indicated to the NFS version 4 client. The
client can then reconnect, and then retry the original request. If
...
... version 4 client. The
client can then reconnect, and then retry the original request. If
the NULL procedure call gets a response, the connection has not
...
... the NULL procedure call gets a response, the connection has not
broken. The client can decide to wait longer for the original
request's response, or it can break the transport connection and
...
... reconnect before re-sending the original request.
For callbacks from the server to the client, the same rules apply,
but the server doing the callback becomes the client, and the client ...
... For callbacks from the server to the client, the same rules apply,
but the server doing the callback becomes the client, and the client
receiving ...
... client, the same rules apply,
but the server doing the callback becomes the client, and the client
receiving the callback becomes the server.
...
... secure channel in which to pass a user
name and password from the client to the server. Once the user name
and password ...
... mandatory set of triples to handle the situations where the initiator
(the client) is anonymous or where the initiator has its own
certificate ...
... NFS version 4 server potentially offering multiple security
mechanisms, the client needs a method to determine or negotiate which
mechanism is to be used for its communication with the server. The
...
... name space
that are available for use by NFS clients. In turn the NFS server
may be configured such that each of these entry points may have
...
...
The security negotiation between client and server must be done with
a secure channel to eliminate the possibility of a third party ...
... third party
intercepting the negotiation sequence and forcing the client and
server to choose a lower level of security than required or desired.
See the section "Security Considerations ...
...
The new SECINFO operation will allow the client to determine, on a
per filehandle basis, what security triple is to be used for server
...
... per filehandle basis, what security triple is to be used for server
access. In general, the client will not have to use the SECINFO
operation except during initial communication with the server or when
the client ...
... client will not have to use the SECINFO
operation except during initial communication with the server or when
the client crosses policy boundaries at the server. It is possible
that the server's policies change during the client's interaction
...
... the client crosses policy boundaries at the server. It is possible
that the server's policies change during the client's interaction
therefore forcing the client to negotiate a new security ...
... that the server's policies change during the client's interaction
therefore forcing the client to negotiate a new security triple.
...
... Based on the assumption that each NFS version 4 client and server
must support a minimum set of security (i.e., LIPKEY ...
... Kerberos-V5 all under RPCSEC_GSS), the NFS client will start its
communication with the server with one of the minimal security ...
... communication with the server with one of the minimal security
triples. During communication with the server, the client may
receive an NFS error of NFS4ERR_WRONGSEC. This error allows the
...
... receive an NFS error of NFS4ERR_WRONGSEC. This error allows the
server to notify the client that the security triple currently being
used is not appropriate for access to the server's filesystem
...
... security triple currently being
used is not appropriate for access to the server's filesystem
resources. The client is then responsible for determining what
security triples are available at the server and choose one which is
...
... security triples are available at the server and choose one which is
appropriate for the client. See the section for the "SECINFO"
operation for further discussion of how the client ...
... client. See the section for the "SECINFO"
operation for further discussion of how the client will respond to
the NFS4ERR_WRONGSEC error and use SECINFO.
...
... database. This is the same
principal the client acquired a GSS-API context for when it issued
...
... LIPKEY may not work for callbacks, since the
LIPKEY client uses a user id/password. If the NFS ...
... SPKM-3 with mutual authentication
be used. This effectively means that the client will use a
certificate to authenticate ...
... o In cases when a host is both an NFS client and server, it can
share the same per-host certificate ...
... for a filesystem object. The contents of the filehandle are opaque
to the client. Therefore, the server is responsible for translating
the filehandle to an internal representation of the filesystem
object.
...
... The operations of the NFS protocol are defined in terms of one or
more filehandles. Therefore, the client needs a filehandle to
initiate communication with the server. With the NFS version 2 ...
... MOUNT protocol is unnecessary for viable interaction between NFS
client and server.
Therefore, the NFS ...
... ROOT of 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 the LOOKUP operation ...
... administrator to define the binding of the PUBLIC filehandle
and server filesystem object. The client may not make any
assumptions about this binding. The client ...
... client may not make any
assumptions about this binding. The client uses the PUBLIC
filehandle via the PUTPUBFH operation.
...
... filesystem reorganization or migration. However, the volatile
filehandle increases the implementation burden for the client.
Since the client ...
... client.
Since the client will need to handle persistent and volatile
filehandles differently, a file attribute is defined which may be
used by the client ...
... client will need to handle persistent and volatile
filehandles differently, a file attribute is defined which may be
used by the client to determine the filehandle types being returned
by the server.
...
...
The filehandle contains all the information the server needs to
distinguish an individual file. To the client, the filehandle is
opaque. The client ...
... client, the filehandle is
opaque. The client stores filehandles for use in a later request and
can compare two filehandles from the same server for equality by
doing a byte-by-byte comparison ...
... can compare two filehandles from the same server for equality by
doing a byte-by-byte comparison. However, the client MUST NOT
otherwise interpret the contents of filehandles. If two filehandles
from the same server are equal, they MUST refer to the same file.
...
... Servers SHOULD try to maintain a one-to-one correspondence between
filehandles and files but this is not required. Clients MUST use
filehandle comparisons only to improve performance, not for correct
...
... filehandle comparisons only to improve performance, not for correct
behavior. All clients need to be prepared for situations in which it
cannot be determined whether two filehandles denote the same object
and in such cases, avoid making invalid assumptions which might cause
...
... volatile filehandle refers to an object that has been removed, the
server should return NFS4ERR_STALE to the client (as is the case for
persistent filehandles). In all other cases where the server
determines that a volatile filehandle can no longer be used, it
...
...
The mandatory attribute "fh_expire_type" is used by the client to
determine what type of filehandle the server is providing for a
particular filesystem. This attribute is a bitmask with the
...
... FH4_VOL_RENAME
The filehandle will expire during rename. This includes a
rename by the requesting client or a rename by any other
client. If FH4_VOL_ANY is set, FH4_VOL_RENAME is
...
... rename by the requesting client or a rename by any other
client. If FH4_VOL_ANY is set, FH4_VOL_RENAME is
redundant.
...
... bits FH4_VOL_MIGRATION and FH4_VOL_RENAME allow the
client to determine that expiration has occurred whenever a specific
event occurs, without an explicit filehandle expiration error from
the server. FH4_VOL_ANY does not provide this form of information.
...
... migration (e.g., all but those that are open),
FH4_VOLATILE_ANY (in this case with FH4_NOEXPIRE_WITH_OPEN) is a
better choice since the client may not assume that all filehandles
will expire when migration occurs, and it is likely that additional
...
... entry/slot
When the client presents a volatile filehandle, the server makes the
following checks, which assume that the check for the volatile bit
...
... Client Recovery from Filehandle Expiration ...
...
If possible, the client SHOULD recover from the receipt of an
NFS4ERR_FHEXPIRED error. The client must take on additional
...
... If possible, the client SHOULD recover from the receipt of an
NFS4ERR_FHEXPIRED error. The client must take on additional
responsibility so that it may prepare itself to recover from the
expiration of a volatile filehandle. If the server returns
...
... responsibility so that it may prepare itself to recover from the
expiration of a volatile filehandle. If the server returns
persistent filehandles, the client does not need these additional
steps.
...
... steps.
For volatile filehandles, most commonly the client will need to store
the component names leading up to and including the filesystem object
in question. With these names, the client ...
... client will need to store
the component names leading up to and including the filesystem object
in question. With these names, the client should be able to recover
by finding a filehandle in the name space that is still available or
...
... If the expired filehandle refers to an object that has been removed
from the filesystem, obviously the client will not be able to recover
from the expired filehandle.
...
...
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 is possible that the original client will not be able to recover.
...
... 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.
However, in the case that the client itself is renaming the file and
...
... it 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
the file is open, it is possible that the client may be able to
...
... 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
recover. The client can determine the new path name based on the
...
... the file is open, it is possible that the client may be able to
recover. The client can determine the new path name based on the
processing of the rename request. The client can then regenerate the
...
... recover. The client can determine the new path name based on the
processing of the rename request. The client can then regenerate the
new filehandle based on the new path name. The client could also use
...
... processing of the rename request. The client can then regenerate the
new filehandle based on the new path name. The client could also use
the compound operation mechanism to construct a set of operations
like:
...
... NFS version 3 fattr3 structure contains a
fixed list of attributes that not all clients and servers are able to
support or care about. The fattr3 structure can not be extended as
new needs arise and it provides no way to indicate non-support ...
... the NFS version 4 protocol, the client is able query what attributes
the server supports and construct requests with only those supported
...
... Named attributes are intended for data needed by applications rather
than by an NFS client implementation. NFS implementors are strongly
...
... as possible but by their definition, the server is not required to
support all of them. Attributes are deemed mandatory if the data is
both needed by a large number of clients and is not otherwise
reasonably computable by the client when support is not provided on
...
... both needed by a large number of clients and is not otherwise
reasonably computable by the client when support is not provided on
the server.
...
...
Note that the hidden directory returned by OPENATTR is a convenience
for protocol processing. The client should not make any assumptions
about the server's implementation of named attributes and whether the
underlying filesystem at the server has a named attribute directory
...
... These MUST be supported by every NFS version 4 client and server in
order to ensure a minimum level of interoperability. The server must
...
... order to ensure a minimum level of interoperability. The server must
store and return these attributes and the client must be able to
function with an attribute set limited to these attributes. With
just the mandatory attributes ...
... function with an attribute set limited to these attributes. With
just the mandatory attributes some client functionality may be
impaired or limited in some ways. A client may ask for any of these
...
... mandatory attributes some client functionality may be
impaired or 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
...
... NFS version 4 protocol. However, they may not be supported on all
clients and servers. A client may ask for any of these attributes to
be returned by setting a bit ...
... version 4 protocol. However, they may not be supported on all
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 set of attributes the server supports and should not request
...
... fail to support attributes which are difficult to support in their
operating environments. A server should provide attributes whenever
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
supported by the server ...
... supported by the server. This will not always be comfortable to
clients but the client is better positioned decide whether and how to
fabricate or construct an attribute or whether to do without the
...
... by the server. This will not always be comfortable to
clients but the client is better positioned decide whether and how to
fabricate or construct an attribute or whether to do without the
attribute.
...
...
It is recommended that servers support arbitrary named attributes. A
client should not depend on the ability to store any named attributes
in the server's filesystem. If a server does support named
attributes, a client ...
... client should not depend on the ability to store any named attributes
in the server's filesystem. If a server does support named
attributes, a client which is also able to handle them should be able
to copy a file's data and meta-data with complete transparency from
...
... specify filehandle
expiration behavior to
the client. See the
section "Filehandles"
for additional
...
... uint64 READ A value created by the
server that the client
can use to determine
if file data,
...
... UTF-8 string. To avoid a representation that is tied to a particular
underlying implementation at the client or server, the use of the
UTF-8 string has been chosen. Note that section 6.1 of [RFC2624 ...
... UTF-8 string has been chosen. Note that section 6.1 of [RFC2624]
provides additional rationale. It is expected that the client and
server will have their own local representation of owner and
owner_group that is used for local storage or presentation to the end
...
... group that is used for local storage or presentation to the end
user. Therefore, it is expected that when these attributes are
transferred between the client and server that the local
representation is translated to a syntax of the form
"user@dns_domain ...
... representation is translated to a syntax of the form
"user@dns_domain". This will allow for a client and server that do
not use the same local representation the ability to translate to a
common syntax that can be interpreted by both.
...
... constraints.
In the case where there is no translation available to the client or
server, the attribute value must be constructed without the "@".
Therefore, the absence of the @ from the owner or owner_group
...
... a basis for translation into its own internal format. Even though
the attribute value can not be translated, it may still be useful.
In the case of a client, the attribute string may be used for local
display of ownership.
...
... group strings that consist of
decimal numeric values with no leading zeros can be given a special
interpretation by clients and servers which choose to provide such
support. The receiver may treat such a user or group ...
... instead. To avoid this mechanism being used to subvert user and
group translation, so that a client might pass all of the owners and
groups in numeric form, a server SHOULD return an NFS4ERR_BADOWNER
...
... error when there is a valid translation for the user or owner
designated in this way. In that case, the client must use the
appropriate name@domain string and not the special form for
...
... access control entries
(ACE). Although, the client can read and write the ACL attribute,
the NFSv4 model is the server does all access control ...
... access control based on the
server's interpretation of the ACL. If at any point the client wants
to check access without issuing an operation that modifies or reads
data or metadata, the client ...
... client wants
to check access without issuing an operation that modifies or reads
data or metadata, the client can use the OPEN and ACCESS operations
to do so. There are various access control entry types, as defined
...
... ACE_TYPE = 0x00000003;
Clients should not attempt to set an ACE unless the server claims
support for that ACE ...
... file) from WRITE_DATA (the ability to modify existing contents); both
masks would be tied to a single "write" permission. When such a
server returns attributes to the client, it would show both
APPEND_DATA and WRITE_DATA if and only if the write permission is
enabled.
...
... access. For example, suppose a server cannot distinguish overwriting
data from appending new data, as described in the previous paragraph.
If a client submits an ACE where APPEND_DATA is set but WRITE_DATA is
not (or vice versa), the server should reject the request with
...
... ACE" flag that applies to both files and
directories, the server may reject the request (i.e., requiring the
client to set both the file and directory inheritance flags). The
server may also accept the request and silently turn on the
ACE4_DIRECTORY_INHERIT_ACE ...
... identifiers cannot be understood when an
NFS client accesses the server, but have meaning when a local process
accesses the file. The ability to display and modify these
permissions is permitted over NFS ...
... ACEs which have respective who fields of "OWNER@", "GROUP@", and
"EVERYONE@" so that the client can see semantically equivalent access
permissions exist whether the client asks for owner, owner_group ...
... "EVERYONE@" so that the client can see semantically equivalent access
permissions exist whether the client asks for owner, owner_group and
mode attributes, or for just the ACL ...
... nothing to do with ACL semantics, it is permitted for clients to
specify both the ACL attribute and mode in the same SETATTR
...
... ACL attribute and mode in the same SETATTR
operation. However, because there is no prescribed order for
processing the attributes in a SETATTR, the client must ensure that
ACL attribute, if specified without mode, would produce the desired
...
... version 3, NFS version 4 allows a client's LOOKUP request
to cross other filesystems. The client ...
... client's LOOKUP request
to cross other filesystems. The client detects the filesystem
crossing whenever the filehandle argument of LOOKUP has an fsid
...
... LOOKUP.
A UNIX-based client will consider this a "mount point crossing".
UNIX has a legacy scheme for allowing a process to determine its
...
... While the NFS version 4 client could simply fabricate a fileid
corresponding to what mounted_on_fileid provides (and if the server
does not support mounted_on_fileid, the client ...
... client could simply fabricate a fileid
corresponding to what mounted_on_fileid provides (and if the server
does not support mounted_on_fileid, the client has no choice), there
is a risk that the client will generate a fileid that conflicts with
...
... does not support mounted_on_fileid, the client has no choice), there
is a risk that the client will generate a fileid that conflicts with
one that is already assigned to another object in the filesystem.
Instead, if the server can provide the mounted_on_fileid, the
...
... one that is already assigned to another object in the filesystem.
Instead, if the server can provide the mounted_on_fileid, the
potential for client operational problems in this area is eliminated.
...
... type of service being provided, the
list will provide a new location or a set of alternate locations for
the filesystem. The client will use this information to redirect its
requests to the new server.
...
... two or more servers. The fs_locations attribute will provide the
list of these locations to the client. On first access of the
filesystem, the client should obtain the value of the fs_locations
...
... list of these locations to the client. On first access of the
filesystem, the client should obtain the value of the fs_locations
attribute. If, in the future, the client finds the server
...
... filesystem, the client should obtain the value of the fs_locations
attribute. If, in the future, the client finds the server
unresponsive, the client may attempt to use another server specified
...
... attribute. If, in the future, the client finds the server
unresponsive, the client may attempt to use another server specified
by fs_locations.
...
... by fs_locations.
If applicable, the client must take the appropriate steps to recover
valid filehandles from the new server ...
... method used to communicate the migration
event between client and server is specified here.
Once the servers participating in the migration ...
... NFS4ERR_MOVED error is returned for all operations except PUTFH and
GETATTR. Upon receiving the NFS4ERR_MOVED error, the client will
obtain the value of the fs_locations attribute. The client will then
...
... receiving the NFS4ERR_MOVED error, the client will
obtain the value of the fs_locations attribute. The client will then
use the contents of the attribute to redirect its requests to the
specified server. To facilitate the use of GETATTR, operations such
...
... the server MUST support the fs_locations attribute.
If the client requests more attributes than just fs_locations, the
server may return fs_locations only. This is to be expected since
the server has migrated the filesystem and may not have a method ...
... solution. The server must consider all of the state information
clients may have outstanding at the server. This includes but is not
limited to locking/share state, delegation ...
... file writes which are represented by WRITE and COMMIT verifiers. The
server should strive to minimize the impact on its clients during and
after the migration process.
...
... server from which the fs_locations attribute was obtained. The
fs_root path is meant to aid the client in locating the filesystem at
the various servers listed.
...
... servers (servA and servB). At servA the filesystem is located at
path "/a/b/c". At servB the filesystem is located at path "/x/y/z".
In this example the client accesses the filesystem first at servA
with a multi-component lookup path of "/a/b/c/d". Since the client ...
... client accesses the filesystem first at servA
with a multi-component lookup path of "/a/b/c/d". Since the client
used a multi-component lookup to obtain the filehandle at "/a/b/c/d",
...
... it is unaware that the filesystem's root is located in servA's name
space 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
...
... 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
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 ...
... if a volatile filehandle from an old server should return an error of
NFS4ERR_FHEXPIRED. Therefore, the client is informed, with the use
of the fh_expire_type attribute, whether volatile filehandles will
expire at the migration ...
... bit
FH4_VOL_MIGRATION is set in the fh_expire_type attribute, the client
must treat the volatile filehandle as if the server had returned the
NFS4ERR_FHEXPIRED error. At the migration ...
... the presence of the FH4_VOL_MIGRATION bit, the client will not
present the original or old volatile filehandle to the new server.
...
... present the original or old volatile filehandle to the new server.
The client will start its communication with the new server by
...
... server's filesystem name space available to NFS clients. More often
portions of the name space are made available via an "export"
...
... root
filehandle for each export is obtained through the MOUNT protocol;
the client sends a string that identifies the export of name space
and the server returns the root ...
... NFS version 4 protocol provides a root filehandle that clients
can use to obtain filehandles for these exports via a multi-component
LOOKUP ...
... user
interface (perhaps a file "Open" dialog window) to find a file via
progressive browsing through a directory tree. The client must be
able to move from one export to another export via single-component,
progressive LOOKUP operations ...
... NFS version 2 and
3 protocols. The client expects all LOOKUP operations to remain
within a single server ...
... within a single server filesystem. For example, the device attribute
will not change. This prevents a client from taking name space paths
that span exports.
...
... that span exports.
An automounter on the client can obtain a snapshot of the server's
name space using the EXPORTS procedure of the MOUNT protocol. If it
...
... image of
the server's name space on the client. The parts of the name space
that are not exported by the server ...
... filesystem to another. There is a drawback to this representation of
the server's name space on the client: it is static. If the server
administrator adds a new export the client ...
... client: it is static. If the server
administrator adds a new export the client will be unaware of it.
...
... name space. An NFS version 4 client uses LOOKUP and READDIR
operations to browse seamlessly from one export to another. Portions
...
... pseudo filesystem, the NFS client should expect that pseudo file
system filehandles are volatile. This can be confirmed by checking
...
... the associated "fh_expire_type" attribute for those filehandles in
question. If the filehandles are volatile, the NFS client must be
prepared to recover a filehandle value (e.g., with a multi-component
LOOKUP ...
... It is the server's responsibility to present the pseudo filesystem
that is complete to the client. If the client sends a lookup request
...
... pseudo filesystem
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
...
...
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.
...
... viewability of portions of the pseudo filesystem based on the
server's perception of the client's ability to authenticate itself
properly. However, with the support of multiple security mechanisms ...
... security mechanisms
and the ability to negotiate the appropriate use of these mechanisms,
the server is unable to properly determine if a client will be able
to authenticate itself. If, based on its policies, the server
...
... chooses to limit the contents of the pseudo filesystem, the server
may effectively hide filesystems from a client that may otherwise
have legitimate access.
...
... state manageable:
o Clear division between client and server
o Ability to reliably detect inconsistency in state ...
...
o Ability to reliably detect inconsistency in state between client
and server
o Simple and robust recovery mechanisms ...
...
In this model, the server owns the state information. The client
communicates its view of this state to the server as needed. The
...
... communicates its view of this state to the server as needed. The
client is also able to detect inconsistent state before modifying a
file.
...
... of granting access or modifying files is managed by the server based
on the client's state. These mechanisms can implement policy ranging
from advisory only locking to full mandatory locking.
...
...
The following sections describe the transition from the heavy weight
information to the eventual stateid used for most client and server
locking and lease interactions.
...
... Client ID ...
...
For each LOCK request, the client must identify itself to the server.
This is done in such a way as to allow for correct lock
...
... operation followed by a SETCLIENTID_CONFIRM operation is required to
establish the identification onto the server. Establishment of
identification by a new incarnation of the client also has the effect
of immediately breaking any leased state that a previous incarnation
...
... of immediately breaking any leased state that a previous incarnation
of the client might have had on the server, as opposed to forcing the
new client incarnation to wait for the leases to expire. Breaking
...
... of the client might have had on the server, as opposed to forcing the
new client incarnation to wait for the leases to expire. Breaking
the lease state amounts to the server removing ...
... delegation state associated with
same client with the same identity. For discussion of delegation ...
... client incarnation verifier that is
used to detect client reboots. Only if the verifier is different
from that which the server has previously recorded the client ...
... client reboots. Only if the verifier is different
from that which the server has previously recorded the client (as
identified by the second field of the structure, id) does the server
start ...
... identified by the second field of the structure, id) does the server
start the process of canceling the client's leased state.
...
...
The second field, id is a variable length string that uniquely
defines the client.
There are several considerations for how the client ...
... string:
o The string should be unique so that multiple clients do not
present the same string. The consequences of two clients
...
... o The string should be unique so that multiple clients do not
present the same string. The consequences of two clients
presenting the same string range from one client ...
... clients
presenting the same string range from one client getting an error
to one client having its leased state ...
... range from one client getting an error
to one client having its leased state abruptly and unexpectedly
canceled.
...
...
o The string should be selected so the subsequent incarnations
(e.g., reboots) of the same client cause the client to present the
same string. The implementor ...
... o The string should be selected so the subsequent incarnations
(e.g., reboots) of the same client cause the client to present the
same string. The implementor is cautioned against an approach
...
... network address
that the client accesses, rather than common to all server network
addresses ...
... addresses. The reason is that it may not be possible for the
client to tell if the same server is listening on multiple network
addresses ...
... multiple network
addresses. If the client issues SETCLIENTID with the same id
string to each network address ...
... network address of such a server, the server will
think it is the same client, and each successive SETCLIENTID will
cause the server to begin the process of removing the client ...
... client, and each successive SETCLIENTID will
cause the server to begin the process of removing the client's
previous leased state.
...
... o The algorithm for generating the string should not assume that the
client's network address won't change. This includes changes
...
... network address won't change. This includes changes
between client incarnations and even changes while the client is
stilling running in its current incarnation. This means that if
...
... address won't change. This includes changes
between client incarnations and even changes while the client is
stilling running in its current incarnation. This means that if
the client ...
... client is
stilling running in its current incarnation. This means that if
the client includes just the client's and server's network address ...
... stilling running in its current incarnation. This means that if
the client includes just the client's and server's network address
...
... network address
in the id string, there is a real risk, after the client gives up
the network address ...
... the network address, that another client, using a similar
algorithm for generating the id string, will generate a
...
... o For a user level NFS version 4 client, it should contain
additional information to distinguish the client from other user
...
... version 4 client, it should contain
additional information to distinguish the client from other user
level clients running on the same host ...
... additional information to distinguish the client from other user
level clients running on the same host, such as a process id or
other unique sequence.
...
... NFS version 4 software was first
installed on the client (though this is subject to the
previously mentioned caution about using information that is
...
... - A true random number. However since this number ought to be
the same between client incarnations, this shares the same
problem as that of the using the timestamp of the software
installation ...
... Note that SETCLIENTID and SETCLIENTID_CONFIRM has a secondary purpose
of establishing the information the server needs to make callbacks to
the client for purpose of supporting delegations. It is permitted to
change this information via SETCLIENTID and SETCLIENTID_CONFIRM
...
... delegations. It is permitted to
change this information via SETCLIENTID and SETCLIENTID_CONFIRM
within the same incarnation of the client without removing the
client ...
...
Once a SETCLIENTID and SETCLIENTID_CONFIRM sequence has successfully
completed, the client uses the shorthand client identifier, of type
clientid4, instead of the longer and less compact nfs_client ...
... Once a SETCLIENTID and SETCLIENTID_CONFIRM sequence has successfully
completed, the client uses the shorthand client identifier, of type
clientid4, instead of the longer and less compact nfs_client_id4
...
... client uses the shorthand client identifier, of type
clientid4, instead of the longer and less compact nfs_client_id4
structure. This shorthand client identifier (a clientid) is assigned
...
... clientid4, instead of the longer and less compact nfs_client_id4
structure. This shorthand client identifier (a clientid) is assigned
by the server and should be chosen so that it will not conflict with
...
... and that clientid is not recognized, as would happen after a server
reboot, the server will reject the request with the error
NFS4ERR_STALE_CLIENTID. When this happens, the client must obtain a
new clientid by use of the SETCLIENTID operation and then proceed to
any other necessary recovery for the server reboot case (See the
...
... Failure and Recovery").
The client must also employ the SETCLIENTID operation when it
receives a NFS4ERR_STALE_STATEID error using a stateid derived from
its current clientid, since this also indicates a server reboot which
...
...
If the server determines that the client holds no associated state
for its clientid, the server may choose to release the clientid. The
...
... state
for its clientid, the server may choose to release the clientid. The
server may make this choice for an inactive client so that resources
are not consumed by those intermittently active clients ...
... client so that resources
are not consumed by those intermittently active clients. If the
client contacts the server after this release, the server must ensure
...
... active clients. If the
client contacts the server after this release, the server must ensure
the client receives the appropriate error so that it will use the
...
... client contacts the server after this release, the server must ensure
the client receives the appropriate error so that it will use the
SETCLIENTID/SETCLIENTID_CONFIRM sequence to establish a new identity.
...
... identity.
It should be clear that the server must be very hesitant to release a
clientid since the resulting work on the client to recover from such
an event will be the same burden as if the server had failed and
restarted. Typically a server would not release a clientid unless
...
... an event will be the same burden as if the server had failed and
restarted. Typically a server would not release a clientid unless
there had been no activity from that client for many minutes.
Note that if the id string in a SETCLIENTID request is properly
...
...
Note that if the id string in a SETCLIENTID request is properly
constructed, and if the client takes care to use the same principal
for each successive use of SETCLIENTID, then, barring an active ...
... returned.
However, client bugs, server bugs, or perhaps a deliberate change of
the principal owner of the id string (such as the case of a client ...
... client bugs, server bugs, or perhaps a deliberate change of
the principal owner of the id string (such as the case of a client
that changes security flavors, and under the new flavor, there is no
...
... NFS4ERR_CLID_INUSE.
In that event, when the server gets a SETCLIENTID for a client id
that currently has no state, or it has state ...
...
When requesting a lock, the client must present to the server the
clientid and an identifier for the owner of the requested lock.
...
...
o A clientid returned by the server as part of the client's use of
the SETCLIENTID operation.
...
... o A variable length opaque array used to uniquely define the owner
of a lock managed by the client.
This may be a thread id, process id, or other unique value.
...
... This requirement includes those stateids generated by earlier
instances of the server. From this, the client can be properly
notified of a server restart. This notification ...
... restart. This notification will occur when the
client presents a stateid to the server from a previous
instantiation.
...
...
This error condition will only occur when the client issues a
locking request which changes a stateid while an I/O request that
uses that stateid is outstanding.
...
... This error condition will occur when there has been a logic error
on the part of the client or server. This should not happen.
One mechanism that may be used to satisfy these requirements ...
... record locks and share reservations, are held by the lockowner. If
no state is established by the client, either record lock or share
reservation, a stateid of all bits ...
... record locks, however, prevent conflicting I/O operations. When they
are attempted, they are rejected with NFS4ERR_LOCKED. When the
client gets NFS4ERR_LOCKED on a file it knows it has the proper share
reservation for, it will need to issue a LOCK request on the region
...
... NFS version 3, there was no notion of a stateid so there was no
way to tell if the application process of the client sending the READ
or WRITE operation had also acquired the appropriate record lock on
the file. Thus there was no way to implement mandatory locking.
...
... READ, the server may perform the corresponding check on the access
mode, or it may choose to allow READ on opens for WRITE only, to
accommodate clients whose write implementation may unavoidably do
reads (e.g., due to buffer ...
... sequence number (r < L) is received,
it is rejected with the return of error NFS4ERR_BAD_SEQID. Given a
properly-functioning client, the response to (r) must have been
received before the last request (L) was sent. If a duplicate of
last request (r == L) is received, the stored response is returned.
...
... rejected with the return of error NFS4ERR_BAD_SEQID. Sequence
history is reinitialized whenever the SETCLIENTID/SETCLIENTID_CONFIRM
sequence changes the client verifier.
...
... It is critical the server maintain the last response sent to the
client to provide a more reliable cache of duplicate non-idempotent
requests than that of the traditional cache ...
... state exists on the server.
The client MUST monotonically increment the sequence number for the
CLOSE, LOCK, LOCKU, OPEN, OPEN_CONFIRM, and OPEN_DOWNGRADE
...
... memory, or other implementation specific details. In any event, the
server is able to do this safely only when the lock_owner no longer
is being utilized by the client. The server may choose to hold the
lock_owner state in the event that retransmitted requests are
...
... state, the server will find that the lock_owner has no files open and
an error will be returned to the client. If the lock_owner does have
a file open, the stateid will not match and again an error is
returned to the client ...
... client. If the lock_owner does have
a file open, the stateid will not match and again an error is
returned to the client.
...
... by the server, the use of the OPEN_CONFIRM operation will
prevent incorrect behavior. When the server observes the use of the
lock_owner for the first time, it will direct the client to perform
the OPEN_CONFIRM for the corresponding OPEN. This sequence
establishes the use of an lock_owner and associated sequence number ...
... sequence number.
Since the OPEN_CONFIRM sequence connects a new open_owner on the
server with an existing open_owner on a client, the sequence number
may have any value. The OPEN_CONFIRM step assures the server that
...
... There are a number of situations in which the requirement to confirm
an OPEN would pose difficulties for the client and server, in that
they would be prevented from acting in a timely fashion on
information received, because that information would be provisional,
...
... created,
found to be unused, and recycled. For CLAIM_DELEGATE_PREV opens, we
are dealing with a client reboot situation. A server which supports
delegation can be sure that no lockowners for that client ...
... client reboot situation. A server which supports
delegation can be sure that no lockowners for that client have been
recycled since client initialization ...
... delegation can be sure that no lockowners for that client have been
recycled since client initialization and thus can ensure that
confirmation will not be required.
...
... RANGE to signify that it does not support sub-range lock
operations. Therefore, the client should be prepared to receive this
error and, if appropriate, report the error to the requesting
application.
...
... application.
The client is discouraged from combining multiple independent locking
ranges that happen to be adjacent into a single request since the
...
... Failure and Recovery" below, the
server may employ certain optimizations during recovery that work
effectively only when the client's behavior during lock recovery is
similar to the client's locking behavior prior to server failure.
...
... effectively only when the client's behavior during lock recovery is
similar to the client's locking behavior prior to server failure.
...
...
If a client has a write lock on a record, it can request an atomic
downgrade of the lock to a read lock via the LOCK request, by setting
...
... the type to READ_LT. If the server supports atomic downgrade, the
request will succeed. If not, it will return NFS4ERR_LOCK_NOTSUPP.
The client should be prepared to receive this error, and if
appropriate, report the error to the requesting application.
...
... appropriate, report the error to the requesting application.
If a client has a read lock on a record, it can request an atomic
upgrade of the lock to a write lock via the LOCK request by setting
...
... succeed. Otherwise, the server will return either NFS4ERR_DENIED or
NFS4ERR_DEADLOCK. The error NFS4ERR_DEADLOCK is returned if the
client issued the LOCK request with the type set to WRITEW_LT and the
server has detected a deadlock. The client should be prepared to
...
... client issued the LOCK request with the type set to WRITEW_LT and the
server has detected a deadlock. The client should be prepared to
receive such errors and if appropriate, report the error to the
requesting application.
...
...
Some clients require the support of blocking locks. The NFS version
4 protocol must not rely on a callback mechanism and therefore is
...
... NFS version
4 protocol must not rely on a callback mechanism and therefore is
unable to notify a client when a previously denied lock has been
granted. Clients have no choice but to continually poll for the
...
... unable to notify a client when a previously denied lock has been
granted. Clients have no choice but to continually poll for the
lock. This presents a fairness problem. Two new lock types are
...
... fairness problem. Two new lock types are
added, READW and WRITEW, and are used to indicate to the server that
the client is requesting a blocking lock. The server should maintain
an ordered list of pending blocking locks. When the conflicting lock
is released, the server may wait the lease period for the first
...
... an ordered list of pending blocking locks. When the conflicting lock
is released, the server may wait the lease period for the first
waiting client to re-request the lock. After the lease period
expires the next waiting client request is allowed the lock. Clients ...
... waiting client to re-request the lock. After the lease period
expires the next waiting client request is allowed the lock. Clients
are required to poll at an interval sufficiently small that it is
...
... client to re-request the lock. After the lease period
expires the next waiting client request is allowed the lock. Clients
are required to poll at an interval sufficiently small that it is
likely to acquire the lock in a timely manner. The server is not
...
... 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, allowing a successful return. In this way, clients can
avoid the burden of needlessly frequent polling for blocking locks.
The server should take care in the length of delay in the event the
...
... avoid the burden of needlessly frequent polling for blocking locks.
The server should take care in the length of delay in the event the
client retransmits the request.
...
... The purpose of a lease is to allow a server to remove stale locks
that are held by a client that has crashed or is otherwise
unreachable. It is not a mechanism for cache consistency ...
...
The following events cause implicit renewal of all of the leases for
a given client (i.e., all those sharing a given clientid). Each of
these is a positive indication that the client is still active ...
... a given client (i.e., all those sharing a given clientid). Each of
these is a positive indication that the client is still active and
that the associated state ...
... bits 1.
Note that if the client had restarted or rebooted, the client
would not be making these requests without issuing the
...
...
Note that if the client had restarted or rebooted, the client
would not be making these requests without issuing the
SETCLIENTID/SETCLIENTID_CONFIRM sequence. The use of the
...
... SETCLIENTID/SETCLIENTID_CONFIRM sequence. The use of the
SETCLIENTID/SETCLIENTID_CONFIRM sequence (one that changes the
client verifier) notifies the server to drop the locking state
...
... verifier) notifies the server to drop the locking state
associated with the client. SETCLIENTID/SETCLIENTID_CONFIRM never
renews a lease.
...
... renewal and in the worst case one RPC is required every lease period
(i.e., a RENEW operation). The number of locks held by the client is
not a factor since all state for the client ...
... by the client is
not a factor since all state for the client is involved with the
lease renewal action.
...
... leases, the server must maintain a common lease expiration time for
all valid leases for a given client. This lease time can then be
easily updated upon implicit lease renewal actions.
...
...
The important requirement in crash recovery is that both the client
and the server know when the other has failed. Additionally, it is
required that a client ...
... client
and the server know when the other has failed. Additionally, it is
required that a client sees a consistent view of data across server
restarts or reboots. All READ and WRITE operations that may have
...
... restarts or reboots. All READ and WRITE operations that may have
been queued within the client or network buffers must wait until the
...
... network buffers must wait until the
client has successfully recovered the locks protecting the READ and
WRITE operations.
...
... Client Failure and Recovery ...
...
In the event that a client fails, the server may recover the client's
locks when the associated leases have expired. Conflicting locks
...
...
In the event that a client fails, the server may recover the client's
locks when the associated leases have expired. Conflicting locks
from another client ...
... client's
locks when the associated leases have expired. Conflicting locks
from another client may only be granted after this lease expiration.
If the client is able to restart ...
... from another client may only be granted after this lease expiration.
If the client is able to restart or reinitialize within the lease
period the client ...
... client is able to restart or reinitialize within the lease
period the client may be forced to wait the remainder of the lease
period before obtaining new locks.
...
... period before obtaining new locks.
To minimize client delay upon restart, lock requests are associated
with an instance of the client ...
... client delay upon restart, lock requests are associated
with an instance of the client by a client supplied verifier. This
...
... restart, lock requests are associated
with an instance of the client by a client supplied verifier. This
verifier ...
... verifier. This
verifier is part of the initial SETCLIENTID call made by the client.
The server returns a clientid as a result of the SETCLIENTID
operation. The client ...
... by the client.
The server returns a clientid as a result of the SETCLIENTID
operation. The client then confirms the use of the clientid with
SETCLIENTID_CONFIRM. The clientid in combination with an opaque
...
... SETCLIENTID_CONFIRM. The clientid in combination with an opaque
owner field is then used by the client to identify the lock owner for
OPEN. This chain of associations is then used to identify all locks
for a particular client ...
... by the client to identify the lock owner for
OPEN. This chain of associations is then used to identify all locks
for a particular client.
Since the verifier ...
...
Since the verifier will be changed by the client upon each
initialization, the server can compare a new verifier ...
... verifier
associated with currently held locks and determine that they do not
match. This signifies the client's new instantiation and subsequent
loss of locking state. As a result, the server is free to release
...
... state (usually as a result of a restart
or reboot), it must allow clients time to discover this fact and re-
establish the lost locking state. The client ...
... clients time to discover this fact and re-
establish the lost locking state. The client must be able to re-
establish the locking state without having the server deny valid ...
... valid
requests because the server has granted conflicting access to another
client. Likewise, if there is the possibility that clients have not
yet re-established their locking state ...
... requests because the server has granted conflicting access to another
client. Likewise, if there is the possibility that clients have not
yet re-established their locking state for a file, the server must
...
... this recovery period is equal to the duration of the lease period.
A client can determine that server failure (and thus loss of locking
state) has occurred, when it receives one of two errors. The
...
... clientid invalidated by reboot or restart. When either of these are
received, the client must establish a new clientid (See the section
"Client ID") and re-establish the locking state ...
... received, the client must establish a new clientid (See the section
"Client ID") and re-establish the locking state as discussed below.
...
... in duration to the lease period, is referred to as the "grace
period". During the grace period, clients recover locks and the
associated state by reclaim-type locking requests (i.e., LOCK
...
...
If the server can reliably determine that granting a non-reclaim
request will not conflict with reclamation of locks by other clients,
the NFS4ERR_GRACE error does not have to be returned and the non-
reclaim client request ...
... clients,
the NFS4ERR_GRACE error does not have to be returned and the non-
reclaim client request can be serviced. For the server to be able to
service READ and WRITE operations during the grace period ...
... between an impending reclaim locking request and the READ or WRITE
operation. If the server is unable to offer that guarantee, the
NFS4ERR_GRACE error must be returned to the client.
For a server to provide simple, valid ...
... grace period.
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
...
... 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
employ a retry mechanism for the request. A delay (on the order of
several seconds) between retries should be used to avoid overwhelming
...
... discussion of the general issue is included in
[Floyd]. The client must account for the server that is able to
perform I/O and non-reclaim locking requests within the grace period
...
... A server may, upon restart, establish a new value for the lease
period. Therefore, clients should, once a new clientid is
established, refetch the lease_time attribute and use it as the basis
for lease renewal for the lease associated with that server.
...
... restart event, a grace
period at least as long as the lease period for the previous server
instantiation. This allows the client state obtained during the
previous server instance to be reliably re-established.
...
... period provided by the server, the server will have not received a
lease renewal from the client. If this occurs, the server may free
all locks held for the client. As a result, all stateids held by the
client ...
... lease renewal from the client. If this occurs, the server may free
all locks held for the client. As a result, all stateids held by the
client will become invalid or stale. Once the client is able to
...
... client. If this occurs, the server may free
all locks held for the client. As a result, all stateids held by the
client will become invalid or stale. Once the client is able to
reach the server after such a network ...
... all locks held for the client. As a result, all stateids held by the
client will become invalid or stale. Once the client is able to
reach the server after such a network partition ...
... reach the server after such a network partition, all I/O submitted by
the client with the now invalid stateids will fail with the server
returning the error NFS4ERR_EXPIRED. Once this error is received,
the client ...
... by
the client with the now invalid stateids will fail with the server
returning the error NFS4ERR_EXPIRED. Once this error is received,
the client will suitably notify the application that held the lock.
As a courtesy to the client ...
... client will suitably notify the application that held the lock.
As a courtesy to the client or as an optimization, the server may
continue to hold locks on behalf of a client for which recent
...
... As a courtesy to the client or as an optimization, the server may
continue to hold locks on behalf of a client for which recent
communication has extended beyond the lease period. If the server
receives a lock or I/O request that conflicts with one of these
...
... client A is unable to renew its lease.
3. Client A's lease expires, so server releases lock.
4. Client ...
... Client A's lease expires, so server releases lock.
4. Client B acquires a lock that would have conflicted with that
of Client A.
...
... client A and server heals.
8. Client A issues a RENEW operation, and gets back a
NFS4ERR_STALE_CLIENTID.
...
... NFS4ERR_STALE_CLIENTID.
9. Client A reclaims its lock within the server's grace period.
...
... grace period.
Thus, at the final step, the server has erroneously granted client
A's lock reclaim. If client B modified the object the lock was
...
... 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, client A will experience object corruption.
...
... A's lock reclaim. If client B modified the object the lock was
protecting, client A will experience object corruption.
The second known edge ...
... network partition, such
that client A is unable to reclaim its lock within the grace
period.
...
...
4. Server's reclaim grace period ends. Client A has no locks
recorded on server.
...
... recorded on server.
5. Client B acquires a lock that would have conflicted with that
of Client A.
...
... client A and server heals.
9. Client A issues a RENEW operation, and gets back a
NFS4ERR_STALE_CLIENTID.
...
... NFS4ERR_STALE_CLIENTID.
10. Client A reclaims its lock within the server's grace period.
...
... edge condition, the final step of the scenario of
the second edge condition has the server erroneously granting client
A's lock reclaim.
...
... in stable storage every lock that is acquired, removing the lock
record from stable storage only when the lock is unlocked by the
client and the lock's lockowner advances the sequence number such
that the lock release is not the last stateful event for the
...
... reclaims, requires that the server record in stable storage
information some minimal information. For example, a server
implementation could, for each client, save in stable storage a
record containing:
...
... client's id string
o a boolean that indicates if the client's lease expired or if there
was administrative intervention (see the section, Server
Revocation ...
... o a timestamp that is updated the first time after a server boot or
reboot the client acquires record locking, share reservation, or
delegation ...
... Assuming the above record keeping, for the first edge condition,
after the server reboots, the record that client A's lease expired
means that another client could have acquired a conflicting record
...
... after the server reboots, the record that client A's lease expired
means that another client could have acquired a conflicting record
lock, share reservation, or delegation ...
... reservation, or delegation. Hence the server must reject
a reclaim from client A with the error NFS4ERR_NO_GRACE.
...
... For the second edge condition, after the server reboots for a second
time, the record that the client had an unexpired record lock, share
reservation, or delegation ...
... reservation, or delegation established before the server's previous
incarnation means that the server must reject a reclaim from client A
with the error NFS4ERR_NO_GRACE.
...
... In the event, after a server reboot, the server determines that
there is unrecoverable damage or corruption to the the stable
storage, then for all clients and/or locks affected, the server
MUST return NFS4ERR_NO_GRACE.
...
... NO_GRACE.
A mandate for the client's handling of the NFS4ERR_NO_GRACE error is
outside the scope of this specification, since the strategies for
...
... NO_GRACE error is
outside the scope of this specification, since the strategies for
such handling are very dependent on the client's operating
environment. However, one potential approach is described below.
...
... environment. However, one potential approach is described below.
When the client receives NFS4ERR_NO_GRACE, it could examine the
change attribute of the objects the client ...
... client receives NFS4ERR_NO_GRACE, it could examine the
change attribute of the objects the client is trying to reclaim state
for, and use that to determine whether to re-establish the state ...
... state via
normal OPEN or LOCK requests. This is acceptable provided the
client's operating environment allows it. In otherwords, the client
implementor is advised to document for his users the behavior. The
client ...
... normal OPEN or LOCK requests. This is acceptable provided the
client's operating environment allows it. In otherwords, the client
implementor is advised to document for his users the behavior. The
client could also inform the application that its record lock or
...
... client's operating environment allows it. In otherwords, the client
implementor is advised to document for his users the behavior. The
client could also inform the application that its record lock or
share reservations (whether they were delegated or not) have been
lost, such as via a UNIX ...
... Revocation" for a discussion of what the
client should do for dealing with unreclaimed delegations on client
...
...
In the event a lock request times out, a client may decide to not
retry the request. The client may also abort the request when the
...
... In the event a lock request times out, a client may decide to not
retry the request. The client may also abort the request when the
process for which it was issued is terminated (e.g., in UNIX due to a
...
... and acted upon it. This would change the state on the server without
the client being aware of the change. It is paramount that the
client re-synchronize state ...
... the client being aware of the change. It is paramount that the
client re-synchronize state with server before it attempts any other
operation that takes a seqid and/or a stateid with the same
...
... Since the server maintains the last lock request and response
received on the lock_owner, for each lock_owner, the client should
cache the last lock request it sent such that the lock request did
...
... cache the last lock request it sent such that the lock request did
not receive a response. From this, the next time the client does a
lock operation for the lock_owner, it can send the cached request, if
there is one, and if the request was one that established state ...
... state
(e.g., a LOCK or OPEN operation), the server will return the cached
result or if never saw the request, perform it. The client can
follow up with a request to remove the state ...
... state (e.g., a LOCKU or CLOSE
operation). With this approach, the sequencing and stateid
information on the client and server for the given lock_owner will
re-synchronize and in turn the lock state will re-synchronize.
...
...
At any point, the server can revoke locks held by a client and the
client must be prepared for this event. When the client ...
... 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
its locks have been or may have been revoked, the client ...
... client and the
client must be prepared for this event. When the client detects that
its locks have been or may have been revoked, the client is
...
... client must be prepared for this event. When the client detects that
its locks have been or may have been revoked, the client is
responsible for validating the state information between itself and
...
... state information between itself and
the server. Validating locking state for the client means that it
must verify or reclaim state for each lock currently held.
...
... revocation is upon server reboot or re-
initialization. In this instance the client will receive an error
(NFS4ERR_STALE_STATEID or NFS4ERR_STALE_CLIENTID) and the client will
...
... initialization. In this instance the client will receive an error
(NFS4ERR_STALE_STATEID or NFS4ERR_STALE_CLIENTID) and the client will
proceed with normal crash recovery as described in the previous
section.
...
... revocation event is the inability to renew the lease
before expiration. While this is considered a rare or unusual event,
the client must be prepared to recover. Both the server and client
will be able to detect the failure to renew the lease and are capable
...
... before expiration. While this is considered a rare or unusual event,
the client must be prepared to recover. Both the server and client
will be able to detect the failure to renew the lease and are capable
of recovering without data corruption. For the server, it tracks the
...
... will be able to detect the failure to renew the lease and are capable
of recovering without data corruption. For the server, it tracks the
last renewal event serviced for the client and knows when the lease
will expire. Similarly, the client must track operations which will
...
... last renewal event serviced for the client and knows when the lease
will expire. Similarly, the client must track operations which will
renew the lease period. Using the time that each such request was
...
... renew the lease period. Using the time that each such request was
sent and the time that the corresponding reply was received, the
client should bound the time that the corresponding renewal could
have occurred on the server and thus determine if it is possible that
a lease period expiration could have occurred.
...
... administrator has decided to release or revoke a particular lock held
by the client. As a result of revocation, the client will receive an
...
... by the client. As a result of revocation, the client will receive an
error of NFS4ERR_ADMIN_REVOKED. In this instance the client may
...
... revocation, the client will receive an
error of NFS4ERR_ADMIN_REVOKED. In this instance the client may
assume that only the lock_owner's locks have been lost. The client
...
... error of NFS4ERR_ADMIN_REVOKED. In this instance the client may
assume that only the lock_owner's locks have been lost. The client
notifies the lock holder appropriately. The client may not assume
...
... assume that only the lock_owner's locks have been lost. The client
notifies the lock holder appropriately. The client may not assume
the lease period has been renewed as a result of failed operation.
...
... the lease period has been renewed as a result of failed operation.
When the client determines the lease period may have expired, the
client must mark all locks held for the associated lease as
...
... When the client determines the lease period may have expired, the
client must mark all locks held for the associated lease as
"unvalidated". This means the client has been unable to re-establish
...
... client must mark all locks held for the associated lease as
"unvalidated". This means the client has been unable to re-establish
or confirm the appropriate lock state with the server. As described
...
... in the previous section on crash recovery, there are scenarios in
which the server may grant conflicting locks after the lease period
has expired for a client. When it is possible that the lease period
has expired, the client must validate ...
... has expired for a client. When it is possible that the lease period
has expired, the client must validate each lock currently held to
ensure that a conflicting lock has not been granted. The client ...
... client must validate each lock currently held to
ensure that a conflicting lock has not been granted. The client may
accomplish this task by issuing an I/O request, either a pending I/O
or a zero-length read, specifying the stateid associated with the
...
... or a zero-length read, specifying the stateid associated with the
lock in question. If the response to the request is success, the
client has validated all of the locks governed by that stateid and
re-established the appropriate state ...
... If the I/O request is not successful, then one or more of the locks
associated with the stateid was revoked by the server and the client
must notify the owner.
...
... is a separate and independent mechanism from record locking. When a
client opens a file, it issues an OPEN operation to the server
specifying the type of access required (READ, WRITE, or BOTH) and the
type of access to deny others (deny NONE, READ, WRITE, or BOTH). If
...
... specifying the type of access required (READ, WRITE, or BOTH) and the
type of access to deny others (deny NONE, READ, WRITE, or BOTH). If
the OPEN fails the client will fail the application's open request.
Pseudo-code ...
...
To provide correct share semantics, a client MUST use the OPEN
operation to obtain the initial filehandle and indicate the desired
access and what if any access to deny. Even if the client ...
... client MUST use the OPEN
operation to obtain the initial filehandle and indicate the desired
access and what if any access to deny. Even if the client intends to
use a stateid of all 0's or all 1's, 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. For clients that do not
have a deny mode built into their open programming interfaces, deny
...
... The CLOSE operation removes all share reservations held by the
lock_owner on that file. If record locks are held, the client SHOULD
release all locks before issuing a CLOSE. The server MAY free all
outstanding locks on CLOSE but some servers may not support the CLOSE
...
... state on the server. Without a valid stateid, the server
will assume the client has the least access. For example, a file
opened with deny READ/WRITE cannot be accessed using a filehandle
...
... with no activity.
o All locks for the client are freed as a result of a SETCLIENTID.
Servers may avoid this complexity, at the cost of less complete
...
... bits for all of the OPEN requests completed. Only a single
CLOSE will be done to reset the effects of both OPENs. Note that the
client, when issuing the OPEN, may not know that the same file is in
fact being opened. The above only applies if both OPENs result in
the OPENed object being designated by the same filehandle.
...
... stateids and will require separate CLOSEs to free them.
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
client ...
... client are merged into a single open
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
open file on the server. This is because the union of the access and
deny bits ...
... bits for the remaining opens may be smaller (i.e., a proper
subset) than previously. The OPEN_DOWNGRADE operation is used to
make the necessary change and the client should use it to update the
server so that share reservation ...
... recovery at a cost of increased RENEW or READ (with zero length)
requests. Longer leases are certainly kinder and gentler to servers
trying to handle very large numbers of clients. The number of RENEW
requests drop in proportion to the lease time. The disadvantages of
long leases are slower recovery after server failure (the server must
...
... wait for the leases to expire and the grace period to elapse before
granting new lock requests) and increased file contention (if client
fails to transmit an unlock request then server must wait for lease
expiration before granting new locks).
...
... lease state from its non-volatile memory and continue operation with
its clients and therefore long leases would not be an issue.
...
... by
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 the lock. There is also the issue of propagation delay across the
...
... retransmitted.
To take propagation delay into account, the client should subtract it
from lease times (e.g., if the client estimates the one-way ...
... To take propagation delay into account, the client should subtract it
from lease times (e.g., if the client estimates the one-way
propagation delay as 200 msec, then it can assume that the lease is
...
... propagation delay as 200 msec, then it can assume that the lease is
already 200 msec old when it gets it). In addition, it will take
another 200 msec to get a response back to the server. So the client
must send a lock renewal or write data back to the server 400 msec
before the lease would expire.
...
... The server's lease period configuration should take into account the
network distance of the clients that will be accessing the server's
resources. It is expected that the lease period will take into
account the network ...
... network propagation delays and other network delay
factors for the client population. Since the protocol does not allow
for an automatic method to determine an appropriate lease period, the
...
... to a new server (migration) or the client chooses to use an alternate
server (e.g., in response to server unresponsiveness) in the context
...
... replication, the appropriate handling of state shared
between the client and server (i.e., locks, leases, stateids, and
clientids) is as described below. The handling differs between
migration ...
... If server replica or a server immigrating a filesystem agrees to, or
is expected to, accept opaque values from the client that originated
from another server, then it is a wise implementation practice for
the servers to encode the "opaque ...
... new server. This must be done in a way that is transparent to the
client. This state transfer will ease the client's transition when a
...
... migration occurs. If the servers are successful in
transferring all state, the client will continue to use stateids
assigned by the original server. Therefore the new server must
...
... be transferred as well. The leases being transferred to the new
server will typically have a different expiration time from those for
the same client, previously on the old server. To maintain the
property that all leases on a given server for a given client ...
... client, previously on the old server. To maintain the
property that all leases on a given server for a given client expire
at the same time, the server should advance the expiration time to
the later of the leases being transferred or the leases already
...
... at the same time, the server should advance the expiration time to
the later of the leases being transferred or the leases already
present. This allows the client to maintain lease renewal of both
classes without special effort.
...
... migration. However, this choice is discouraged. In this case, when
the client presents state information from the original server, the
client ...
... client presents state information from the original server, the
client must be prepared to receive either NFS4ERR_STALE_CLIENTID or
NFS4ERR_STALE_STATEID from the new server. The client ...
... client must be prepared to receive either NFS4ERR_STALE_CLIENTID or
NFS4ERR_STALE_STATEID from the new server. The client should then
recover its state information as it normally would in response to a
...
... leases, stateids and clientids do not have validity across a
transition from one server to another. The client must re-establish
its locks on the new server. This can be compared to the re-
...
... server reboot. The difference is that the server has no provision to
distinguish requests reclaiming locks from those obtaining new locks
or to defer the latter. Thus, a client re-establishing a lock on the
new server (by means of a LOCK or OPEN request), may have the
...
... should not pose large difficulties in practice. When an attempt to
re-establish a lock on a new server is denied, the client should
treat the situation as if his original lock had been revoked.
...
...
In the case of lease renewal, the client may not be submitting
requests for a filesystem that has been migrated to another server.
This can occur because of the implicit lease renewal mechanism. The
...
... requests for a filesystem that has been migrated to another server.
This can occur because of the implicit lease renewal mechanism. The
client renews leases for all filesystems when submitting a request to
any one filesystem at the server.
...
... any one filesystem at the server.
In order for the client to schedule renewal of leases that may have
been relocated to the new server, the client ...
... client to schedule renewal of leases that may have
been relocated to the new server, the client must find out about
lease relocation before those leases expire. To accomplish this, all
operations which implicitly renew leases for a client ...
... client must find out about
lease relocation before those leases expire. To accomplish this, all
operations which implicitly renew leases for a client (i.e., OPEN,
CLOSE, READ, WRITE, RENEW, LOCK, LOCKT, LOCKU), will return the error
NFS4ERR_LEASE_MOVED if responsibility for any of the leases to be
...
... renewed has been transferred to a new server. This condition will
continue until the client receives an NFS4ERR_MOVED error and the
server receives the subsequent GETATTR(fs_locations) for an access to
each filesystem for which a lease has been moved to a new server ...
... new server.
When a client receives an NFS4ERR_LEASE_MOVED error, it should
perform an operation on each filesystem associated with the server in
question. When the client ...
... client receives an NFS4ERR_LEASE_MOVED error, it should
perform an operation on each filesystem associated with the server in
question. When the client receives an NFS4ERR_MOVED error, the
client can follow the normal process to obtain the new server ...
... question. When the client receives an NFS4ERR_MOVED error, the
client can follow the normal process to obtain the new server
information (through the fs_locations attribute) and perform renewal
...
... new server. If the server has not had state
transferred to it transparently, the client will receive either
NFS4ERR_STALE_CLIENTID or NFS4ERR_STALE_STATEID from the new server,
...
... NFS4ERR_STALE_CLIENTID or NFS4ERR_STALE_STATEID from the new server,
as described above, and the client can then recover state information
as it does in the event of server failure.
...
...
In order that the client may appropriately manage its leases in the
case of migration, the destination ...
... migration in which state is
transferred transparently, the client is under no obligation to re-
fetch the lease_time attribute and may continue to use the value
previously fetched (on the source server).
...
...
If state has not been transferred transparently (i.e., the client
sees a real or simulated server reboot), the client should fetch the
...
... state has not been transferred transparently (i.e., the client
sees a real or simulated server reboot), the client should fetch the
value of lease_time on the new (i.e., destination) server, and use it
...
... grace period at least as long as the lease_time on the source server,
in order to ensure that clients have ample time to reclaim their
locks before potentially conflicting non-reclaimed locks are granted.
The means by which the new server ...
... Client-Side Caching ...
...
Client-side caching of data, of file attributes, and of file names is
essential to providing good performance with the NFS ...
... NFS protocol have not attempted it.
Instead, several NFS client implementation techniques have been used
to reduce the problems that a lack of coherence poses for users.
These techniques have not been clearly defined by earlier protocol
specifications ...
... protocol
specifications and it is often unclear what is valid or invalid
client behavior.
The NFS ...
... defines a more limited set of caching guarantees to allow locks and
share reservations to be used without destructive interference from
client side caching.
In addition, the NFS ...
... mechanism which allows many decisions normally made by the server to
be made locally by clients. This mechanism provides efficient
support of the common cases where sharing is infrequent or where
sharing is read-only.
...
... Performance Challenges for Client-Side Caching ...
... scalability challenges can arise when those techniques are used with
very large numbers of clients. This is particularly true when
clients are geographically distributed which classically increases
...
... very large numbers of clients. This is particularly true when
clients are geographically distributed which classically increases
the latency for cache ...
... behavior can have serious performance drawbacks. A common case is
one in which a file is only accessed by a single client. Therefore,
sharing is infrequent.
...
... conflicts exist is expensive. A better option with regards to
performance is to allow a client that repeatedly opens a file to do
so without reference to the server. This is done until potentially
conflicting operations from another client ...
... client that repeatedly opens a file to do
so without reference to the server. This is done until potentially
conflicting operations from another client actually occur.
A similar situation arises in connection ...
... delegation of server responsibilities for a file to a
client improves performance by avoiding repeated requests to the
server in the absence of inter-client ...
... client improves performance by avoiding repeated requests to the
server in the absence of inter-client conflict. With the use of a
"callback" RPC from server to client ...
... client conflict. With the use of a
"callback" RPC from server to client, a server recalls delegated
responsibilities when another client engages in sharing of a
...
... RPC from server to client, a server recalls delegated
responsibilities when another client engages in sharing of a
delegated file.
...
...
A delegation is passed from the server to the client, specifying the
object of the delegation and the type of delegation ...
... delegation is associated with a clientid and may be
used on behalf of all the open_owners for the given client. A
delegation is made to the client ...
... client. A
delegation is made to the client as a whole and not to any specific
process or thread of control within it.
...
... CB_NULL procedure checks the continuity of the callback path. A
server makes a preliminary assessment of callback availability to a
given client and avoids delegating responsibilities until it has
determined that callbacks are supported. Because the granting of a
delegation ...
... delegation is always conditional upon the absence of conflicting
access, clients must not assume that a delegation will be granted and
they must always be prepared for OPENs to be processed without any
...
... is an associated lease that is subject to renewal together with all
of the other leases held by that client.
Unlike locks, an operation by a second client ...
... client.
Unlike locks, an operation by a second client to a delegated file
will cause the server to recall a delegation through a callback.
...
... delegation through a callback.
On recall, the client holding the delegation must flush modified
state ...
... delegation. The conflicting request will not receive a response
until the recall is complete. The recall is considered complete when
the client returns the delegation or the server times out on the
recall and revokes the delegation ...
... delegation as a result of the timeout.
Following the resolution of the recall, the server has the
information necessary to grant or deny the second client's request.
At the time the client ...
... client's request.
At the time the client receives a delegation recall, it may have
substantial state ...
... delegation to be
returned since it may involve numerous RPCs to the server. If the
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
...
...
An example of this is when responsibility to mediate opens on a given
file is delegated to a client (see the section "Open Delegation").
The server will not know what opens are in effect on the client ...
... client (see the section "Open Delegation").
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
access and deny state ...
... delegation for the file has been returned.
A client failure or a network partition can result in failure to
...
... partition (full or callback-only)
In the event the client reboots or restarts, the failure to renew
leases will result in the revocation ...
... There will be situations in which delegations will need to be
reestablished after a client reboots or restarts. The reason for
this is the client ...
... client reboots or restarts. The reason for
this is the client may have file data stored locally and this data
was associated with the previously held delegations. The client ...
... client may have file data stored locally and this data
was associated with the previously held delegations. The client will
need to reestablish the appropriate file state on the server.
...
... state on the server.
To allow for this type of client recovery, the server MAY 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
with these delegations will need to wait. Because the normal recall
process ...
... with these delegations will need to wait. Because the normal recall
process may require significant time for the client to flush changed
state to the server, other clients ...
... client to flush changed
state to the server, other clients need be prepared for delays that
occur because of a conflicting delegation. This longer interval
...
... occur because of a conflicting delegation. This longer interval
would increase the window for clients to reboot and consult stable
storage so that the delegations can be reclaimed. For open
...
... delegations upon SETCLIENTID_CONFIRM, and
instead MUST, for a period of time no less than that of the value of
the lease_time attribute, maintain the client's delegations to allow
time for the client ...
... client's delegations to allow
time for the client to issue CLAIM_DELEGATE_PREV requests. The
server that supports CLAIM_DELEGATE_PREV MUST support the DELEGPURGE
operation.
...
... server grants the delegation but a special designation is applied so
that the client treats the delegation as having been granted but
recalled by the server ...
... delegation as having been granted but
recalled by the server. Because of this, the client has the duty to
write all modified state to the server and then return the
...
... version 4 protocol:
o Upon reclaim, a client reporting resources assigned to it by an
earlier server instance must be granted those resources.
...
... to be continued.
o The use of callbacks is not to be depended upon until the client
has proven its ability to receive them.
...
... however, the server may extend the period in which conflicting
requests are held off. Eventually the occurrence of a conflicting
request from another client will cause revocation of the delegation.
...
... delegation will result.
A client normally finds out about revocation of a delegation when it
...
... delegation revocation
after a client reboot when it attempts to reclaim a delegation and
receives that same error. Note that in the case of a revoked write
...
... open delegation, there are issues because data may have been modified
by the client whose delegation is revoked and separately by other
clients ...
... by the client whose delegation is revoked and separately by other
clients. See the section "Revocation Recovery for Write Open
Delegation ...
... which a server reboots after revoking a delegation but before the
client holding the revoked delegation is notified about the
revocation ...
... implemented so as to take account of the possibility of conflicting
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.
Share reservations and record locks are the facilities the NFS ...
... applications rely on, NFS version 4 clients should not provide cached
data to applications or modify it on behalf of an application when it
would not be valid ...
... clients.
o First, cached data present on a client must be revalidated after
doing an OPEN. Revalidating means that the client fetches the
...
... o First, cached data present on a client must be revalidated after
doing an OPEN. Revalidating means that the client fetches the
change attribute from the server, compares it with the cached
change attribute, and if different, declares the cached data (as
...
... well as the cached attributes) as invalid. This is to ensure that
the data for the OPENed file is still correctly reflected in the
client's cache. This validation must be done at least when the
...
... cache. This validation must be done at least when the
client's OPEN operation includes DENY=WRITE or BOTH thus
terminating a period in which other clients ...
... client's OPEN operation includes DENY=WRITE or BOTH thus
terminating a period in which other clients may have had the
opportunity to open the file with WRITE access. Clients may
...
... terminating a period in which other clients may have had the
opportunity to open the file with WRITE access. Clients may
choose to do the revalidation more often (i.e., at OPENs
specifying DENY ...
...
Since the change attribute is updated for data and metadata
modifications, some client implementors may be tempted to use the
time_modify attribute and not change to validate cached data, so
...
...
whereas time_modify is guaranteed to change only at the
granularity of the time_delta attribute. Use by the client's data
cache validation ...
... cache validation logic of time_modify and not change runs the risk
of the client incorrectly marking stale data as valid.
...
... a file OPENed for write. This is complementary to the first rule.
If the data is not flushed at CLOSE, the revalidation done after
client OPENs as file is unable to achieve its purpose. The other
aspect to flushing the data before close is that the data must be
committed to stable storage, at the server, before the CLOSE
...
... aspect to flushing the data before close is that the data must be
committed to stable storage, at the server, before the CLOSE
operation is requested by the client. In the case of a server
reboot or restart and a CLOSEd file, it may not be possible to
...
... share reservations to exclude inconsistent file access, there is an
analogous set of constraints that apply to client side data caching.
These rules are effective only if the file locking is used in a way
that matches in an equivalent way the actual READ and WRITE
...
... NFS version 4 protocol unless clients refrain from data caching.
The rules for data caching in the file locking environment are:
...
... The rules for data caching in the file locking environment are:
o First, when a client obtains a file lock for a particular region,
the data cache corresponding to that region (if any cached data
...
... exists) must be revalidated. If the change attribute indicates
that the file may have been updated since the cached data was
obtained, the client must flush or invalidate the cached data for
the newly locked region. A client might choose to invalidate all
...
... obtained, the client must flush or invalidate the cached data for
the newly locked region. A client might choose to invalidate all
of non-modified cached data that it has for the file but the only
requirement ...
... data must reflect the actual byte ranges locked or unlocked.
Rounding these up or down to reflect client cache block boundaries
will cause problems if not carefully done. For example, writing a
...
... unlocked may cause invalid modification to the region outside the
unlocked area. This, in turn, may be part of a region locked by
another client. Clients can avoid this situation by synchronously
...
... unlocked area. This, in turn, may be part of a region locked by
another client. Clients can avoid this situation by synchronously
performing portions of write operations that overlap that portion
...
... a locked area which is 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 procedure shows that the data which the
client ...
... client to read one or two partial blocks from the
server if the revalidation procedure shows that the data which the
client possesses may not be valid.
...
... The data that is written to the server as a prerequisite to the
unlocking of a region must be written, at the server, to stable
storage. The client may accomplish this either with synchronous
writes or by following asynchronous ...
... This is required because retransmission of the modified data after a
server reboot might conflict with a lock held by another client.
A client ...
... client.
A client implementation may choose to accommodate applications which
use record locking in non-standard ways (e.g., using a record lock as
...
... range. This may include modified data
within files other than the one for which the unlocks are being done.
In such cases, the client must not interfere with applications whose
READs and WRITEs are being done only within the bounds of record
locks which the application holds. For example, an application locks
...
... locks which the application holds. For example, an application locks
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
the server could validly write that single byte in response to an
unrelated unlock. However, it would not be valid ...
... valid to write the entire
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.
Client implementations can avoid this problem by dividing files with
...
... an area that is not locked and might be locked by another client.
Client implementations can avoid this problem by dividing files with
modified data into those for which all modifications are done to
areas covered by an appropriate record lock and those for which there
...
... the former class of files must not include areas not locked and thus
not modified on the client.
...
...
Client side data caching needs to respect mandatory file locking when
it is in effect. The presence of mandatory file locking for a given
file is indicated when the client ...
... Client side data caching needs to respect mandatory file locking when
it is in effect. The presence of mandatory file locking for a given
file is indicated when the client gets back NFS4ERR_LOCKED from a
READ or WRITE on a file it has an appropriate share reservation for.
...
... READ or WRITE on a file it has an appropriate share reservation for.
When mandatory locking is in effect for a file, the client must check
for an appropriate file lock for data being read or written. If a
lock exists for the range ...
... for an appropriate file lock for data being read or written. If a
lock exists for the range being read or written, the client may
satisfy the request using the client's validated ...
... range being read or written, the client may
satisfy the request using the client's validated cache. If an
...
... appropriate file 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 must be sent to the server for processing. When a
...
...
When clients cache data, the file data needs to be organized
according to the filesystem object to which the data belongs. For
...
... NFS version 3 clients, the typical practice has been to assume for
the purpose of caching that distinct filehandles represent distinct
filesystem objects. The client ...
... clients, the typical practice has been to assume for
the purpose of caching that distinct filehandles represent distinct
filesystem objects. The client then has the choice to organize and
maintain the data cache on this basis.
...
... significant deviations from a "one filehandle per object" model
because a filehandle may be constructed on the basis of the object's
pathname. Therefore, clients need a reliable method to determine if
two filehandles designate the same filesystem object. If clients ...
... clients need a reliable method to determine if
two filehandles designate the same filesystem object. If clients
were simply to assume that all distinct filehandles denote distinct
objects and proceed to do data caching on this basis, caching
...
... were simply to assume that all distinct filehandles denote distinct
objects and proceed to do data caching on this basis, caching
inconsistencies would arise between the distinct client side objects
which mapped to the same server side object.
...
... version 3 protocol. Without this method, caching
inconsistencies within the same client could occur and this has not
been present in previous versions of the NFS ...
... NFS protocol. Note that it
is possible to have such inconsistencies with applications executing
on multiple clients but that is not the issue being addressed here.
For the purposes of data caching, the following steps allow an NFS ...
... NFS
version 4 client to determine whether two distinct filehandles denote
the same server side object:
...
... fileid attribute for both of the handles, then it cannot be
determined whether the two objects are the same. Therefore,
operations which depend on that knowledge (e.g., client side data
caching) cannot be done reliably.
...
...
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
delegation is recallable, since the circumstances that allowed for
...
... delegation are subject to change. In particular, the server may
receive a conflicting OPEN from another client, the server must
recall the delegation before deciding whether the OPEN from the other
...
... recall the delegation before deciding whether the OPEN from the other
client may be granted. Making a delegation is up to the server and
clients ...
... client 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 result in an open delegation. The following is a typical
...
... should be delegated:
o The client must be able to respond to the server's callback
requests. The server will use the CB_NULL procedure for a test of
callback ability.
...
... callback ability.
o The client must have responded properly to previous recalls.
o There must be no current open conflicting with the requested
...
... OPEN/CLOSE that
would make the required handling incompatible with the prescribed
handling that the delegated client would apply (see below).
There are two types of open delegations ...
... delegations, read and write. A read open
delegation allows a client to handle, on its own, requests to open a
file for reading that do not deny read access to others. Multiple
read open delegations ...
... delegations may be outstanding simultaneously and do not
conflict. A write open delegation allows the client to handle, on
its own, all opens. Only one write open delegation may exist for a
...
... delegations.
When a client has a read open delegation, it may not make any changes
to the contents or attributes of the file but it is assured that no
...
... delegation, it may not make any changes
to the contents or attributes of the file but it is assured that no
other client may do so. When a client has a write open delegation,
...
... to the contents or attributes of the file but it is assured that no
other client may do so. When a client has a write open delegation,
it may modify the file data since no other client ...
... client has a write open delegation,
it may modify the file data since no other client will be accessing
the file's data. The client holding a write delegation ...
... it may modify the file data since no other client will be accessing
the file's data. The client holding a write delegation may only
affect file attributes which are intimately connected with the file
...
... data: size, time_modify, change.
When a client has an open delegation, it does not send OPENs or
CLOSEs to the server but updates the appropriate status internally.
...
... open.
When a request internal to the client is made to open a file and open
delegation is in effect, it will be accepted or rejected solely on
...
... server authentication will ever 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
authentication, the client ...
... client is depending on the server for
authentication, the client should be sure authentication occurs for
each user by use of the ACCESS operation. This should be the case
...
... delegation provides a
guarantee that no open and thus no read or write has been done by
another client.
For the purposes of open delegation ...
... bits.
Therefore, READs or WRITEs with a special stateid done by another
client will force the server to recall a write open delegation. A
WRITE with a special stateid done by another client ...
... client will force the server to recall a write open delegation. A
WRITE with a special stateid done by another client will force a
recall of read open delegations.
...
...
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 the usual point at which the client ...
... client is able to avoid writing data to the
server when the CLOSE of a file is serviced. The file close system
call is the usual point at which the client is notified of a lack of
stable storage for the modified file data generated by the
application. At the close, file data is written to the server and
...
... alternative method be in place for the same type of communication to
occur between client and server.
In the delegation ...
... 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
flush data to the server of a size equal to that provided in the
original delegation ...
... The server can recall delegations as a result of managing the
available filesystem space. The client should abide by the server's
state ...
... state space limits for delegations. If the client exceeds the stated
limits for the delegation, the server's behavior is undefined.
...
... authentication, flushing modified data to the server
after a CLOSE has occurred may be problematic. For example, the user
of the application may have logged off the client and unexpired
authentication credentials ...
... authentication credentials may not be present. In this case, the
client may need to take special care to ensure that local unexpired
credentials ...
...
When a client holds a write open delegation, lock operations may be
performed locally. This includes those required for mandatory file
...
... done.
When a client holds a read open delegation, lock operations are not
performed locally. All lock operations, including those requesting
...
... target is a file that has a write open delegation in effect. The
reason for this is that the client holding the write delegation may
have modified the data and the server needs to reflect this change to
...
... delegation may
have modified the data and the server needs to reflect this change to
the second client that submitted the GETATTR. Therefore, the client
holding the write delegation ...
... have modified the data and the server needs to reflect this change to
the second client that submitted the GETATTR. Therefore, the client
holding the write delegation needs to be interrogated. The server
...
... query via CB_GETATTR are size and change.
Since CB_GETATTR is being used to satisfy another client's GETATTR
request, the server only needs to know if the client holding the
...
... Since CB_GETATTR is being used to satisfy another client's GETATTR
request, the server only needs to know if the client holding the
delegation has a modified version ...
... 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
satisfy the second client ...
... client's copy
of the delegated file is not modified (data or size), the server can
satisfy the second client's GETATTR request from the attributes
stored locally at the server. If the file is modified, the server
only needs to know about this modified state ...
... state. If the server
determines that the file is currently modified, it will respond to
the second client's GETATTR as if the file had been modified locally
at the server.
...
... and is opaque to the client, the client and server need to agree on a
method of communicating the modified state ...
... method of communicating the modified state of the file. For the 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.
For the client, the following steps will be taken when receiving a
write delegation ...
... and cached. Let this value be represented by c.
o The client will create a value greater than c that will be used
for communicating modified data is held at the client ...
... client will create a value greater than c that will be used
for communicating modified data is held at the client. Let this
value be represented by d.
...
... value be represented by d.
o 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, the value d is returned for the change attribute
...
... attribute, it checks to see if it holds modified data. If the
file is modified, the value d is returned for the change attribute
value. If this file is not currently modified, the client returns
the value c for the change attribute.
...
... the value c for the change attribute.
For simplicity of implementation, the client MAY for each CB_GETATTR
return the same value d. This is true even if, between successive
CB_GETATTR operations, the client ...
... client MAY for each CB_GETATTR
return the same value d. This is true even if, between successive
CB_GETATTR operations, the client again modifies in the file's data
or metadata in its cache. The client ...
... client again modifies in the file's data
or metadata in its cache. The client can return the same value
because the only requirement is that the client ...
... client can return the same value
because the only requirement is that the client be able to indicate
to the server that the client holds modified data. Therefore, the
...
... requirement is that the client be able to indicate
to the server that the client holds modified data. Therefore, the
value of d may always be c + 1.
...
...
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
change with, it is not opaque ...
... 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 unsigned integer, and the server has to be able to see the results
...
... an 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
encode the change attribute in network ...
... encode the change attribute in network order when sending it to the
client. The client MUST decode it from network order to its native
...
... network order when sending it to the
client. The client MUST decode it from network order to its native
order when receiving ...
... network order to its native
order when receiving it and the client MUST encode it network order
when sending it to the server. For this reason, change is defined as
...
... delegation. Let this value be represented by sc.
o When a second client sends a GETATTR operation on the same file to
the server, the server obtains the change attribute from the first
client ...
... client sends a GETATTR operation on the same file to
the server, the server obtains the change attribute from the first
client. Let this value be cc.
o If the value cc is equal to sc, the file is not modified and the
...
... o 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
time_modify (for example) to the second client.
o If the value cc is NOT equal to sc, the file is currently modified
...
...
o If the value cc is NOT equal to sc, the file is currently modified
at 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 attribute values for time_metadata and time_modify. A
...
... nsc. To prevent the possibility of time_modify, time_metadata,
and change from appearing to go backward (which would happen if
the client holding the delegation fails to write its modified data
to the server before the delegation ...
... storage is OPTIONAL.
As discussed earlier in this section, the client MAY return the
same cc value on subsequent CB_GETATTR calls, even if the file was
modified in the client ...
... client MAY return the
same 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. Therefore, the server must assume that the file
...
... }
return to client (that sent GETATTR) the attributes
it requested, but make sure size comes from what
CB_GETATTR returned. Do not update ...
... CB_GETATTR returned. Do not update the file's metadata
with the client's modified size.
o In the case that the file attribute size is different than the
...
... server's current value, the server treats this as a modification
regardless of the value of the change attribute retrieved via
CB_GETATTR and responds to the second client as in the last step.
This methodology resolves issues of clock differences between client
and server ...
... client as in the last step.
This methodology resolves issues of clock differences between client
and server and other scenarios where the use of CB_GETATTR break
down.
...
... delegations at any time if resource constraints make it
advisable to do so. Clients should always be prepared for the
possibility of recall.
...
... possibility of recall.
When a client receives a recall for an open delegation, it needs to
update ...
... state on the server before returning the delegation. These
same updates must be done whenever a client chooses to return a
delegation voluntarily. The following items of state ...
... operation must be sent to the server.
o If a file has other open references at the client, then OPEN
operations must be sent to the server. The appropriate stateids
will be provided by the server ...
... operations must be sent to the server. The appropriate stateids
will be provided by the server for subsequent use by the client
since the delegation stateid will not longer be valid ...
... will allow the presentation of the delegation stateid so that the
client can establish the appropriate rights to perform the OPEN.
(see the section "Operation 18: OPEN" for details.)
...
... not open for write, all modified data for the file must be flushed
to the server. If the delegation had not existed, the client
would have done this data flush before the CLOSE operation.
...
... effect. However, because the write open delegation implies no other
locking by other clients, a simpler implementation is to flush all
modified data for the file (as described just above) if any write
lock has been released while the write open delegation ...
... the case of closing the open that resulted in obtaining the
delegation would clients be likely to do this early, since, in that
case, the close once done will not be undone. Regardless of the
client ...
... clients be likely to do this early, since, in that
case, the close once done will not be undone. Regardless of the
client's choices on scheduling these actions, all must be performed
before the delegation is returned, including (when applicable) the
...
... Clients that Fail to Honor Delegation Recalls ...
...
A client may fail to respond to a recall for various reasons, such as
a failure of the callback path from server to the client. The client ...
... A client may fail to respond to a recall for various reasons, such as
a failure of the callback path from server to the client. The client
may be unaware of a failure in the callback path. This lack of
...
... client may fail to respond to a recall for various reasons, such as
a failure of the callback path from server to the client. The client
may be unaware of a failure in the callback path. This lack of
awareness could result in the client ...
... client
may be unaware of a failure in the callback path. This lack of
awareness could result in the client finding out long after the
failure that its delegation has been revoked, and another client ...
... client finding out long after the
failure that its delegation has been revoked, and another client has
modified the data for which the client had a delegation ...
... delegation has been revoked, and another client has
modified the data for which the client had a delegation. This is
especially a problem for the client ...
... client had a delegation. This is
especially a problem for the client that held a write delegation.
...
... delegation.
The server also has a dilemma in that the client that fails to
respond to the recall might also be sending other NFS requests,
...
... including those that renew the lease before the lease expires.
Without returning an error for those lease renewing operations, the
server leads the client to believe that the delegation it has is in
force.
...
... delegation if one of the following occurs:
- The client has issued a RENEW operation and the server has
returned an NFS4ERR_CB_PATH_DOWN error. The server MUST renew
...
... PATH_DOWN error. The server MUST renew
the lease for any record locks and share reservations the
client has that the server has known about (as opposed to those
locks and share reservations the client has established but not
...
... client has that the server has known about (as opposed to those
locks and share reservations the client has established but not
yet sent to the server, due to the delegation). The server
...
... yet sent to the server, due to the delegation). The server
SHOULD give the client a reasonable time to return its
delegations to the server before revoking the client ...
... client a reasonable time to return its
delegations to the server before revoking the client's
delegations.
...
... delegations.
- The client has not issued a RENEW operation for some period of
time after the server attempted to recall the delegation. This
...
... lease_time attribute.
o When the client holds a delegation, it can not rely on operations,
except for RENEW, that take a stateid, to renew delegation ...
... except for RENEW, that take a stateid, to renew delegation leases
across callback path failures. The client that wants to keep
delegations in force across callback path failures must use RENEW
...
... At the point a delegation is revoked, if there are associated opens
on the client, the applications holding these opens need to be
notified. This notification usually occurs by returning errors for
...
... notification of the revocation is unnecessary.
However, if there is modified data present at the client for the
file, the user of the application should be notified. Unfortunately,
it may not be possible to notify the user since active ...
... it may not be possible to notify the user since active applications
may not be present at the client. See the section "Revocation
Recovery for Write Open Delegation ...
... revocation must be removed from the
client. In the case of modified data existing in the client's cache,
...
... removed from the
client. In the case of modified data existing in the client's cache,
that data must be removed ...
... cache,
that data must be removed from the client without it being written to
the server. As mentioned, the assumptions made by the client are no
...
... removed from the client without it being written to
the server. As mentioned, the assumptions made by the client are no
longer valid at the point when a lock or delegation ...
... valid at the point when a lock or delegation has been revoked.
For example, another client may have been granted a conflicting lock
after the revocation of the lock at the first client ...
... client may have been granted a conflicting lock
after the revocation of the lock at the first client. Therefore, the
data within the lock range may have been modified by the other
...
... data within the lock range may have been modified by the other
client. Obviously, the first client is unable to guarantee to the
application what has occurred to the file in the case of revocation ...
... range may have been modified by the other
client. Obviously, the first client is unable to guarantee to the
application what has occurred to the file in the case of revocation.
...
... 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
make such notification impossible because errors for certain
...
... this is that an invariant for which an application depends on may be
violated. Depending on how errors are typically treated for the
client operating environment, further levels of notification
including logging, console messages, and GUI ...
... Revocation recovery for a write open delegation poses the special
issue of modified data in the client cache while the file is not
open. In this situation, any client ...
... client cache while the file is not
open. In this situation, any client which does not flush modified
data to the server on each close must ensure that the user receives
appropriate notification ...
... messages are typical examples.
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
...
... 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 file data as modified during the delegation under a different
...
... name in the filesystem name space to ease recovery. Note that when
the client can determine that the file has not been modified by any
other client, or when the client ...
... the client can determine that the file has not been modified by any
other client, or when the client has a complete cached copy of file
in question, such a saved copy of the client ...
... client can determine that the file has not been modified by any
other client, or when the client has a complete cached copy of file
in question, such a saved copy of the client's view of the file may
...
... client, or when the client has a complete cached copy of file
in question, such a saved copy of the client's view of the file may
be of particular value for recovery. In other case, recovery using a
copy of the file based partially on the client ...
... client's view of the file may
be of particular value for recovery. In other case, recovery using a
copy of the file based partially on the client's cached data and
partially on the server copy as modified by other clients, will be
...
... copy of the file based partially on the client's cached data and
partially on the server copy as modified by other clients, will be
anything but straightforward, so clients may avoid saving file
...
... partially on the server copy as modified by other clients, will be
anything but straightforward, so clients may avoid saving file
contents in these situations or mark the results specially to warn
users of possible problems.
...
... sufficient disk space is available within the target filesystem.
Such saving may also be restricted to situations when the client has
sufficient buffering resources to keep the cached copy available
...
... pathnames and similarly for directory contents.
Clients may cache file attributes obtained from the server and use
them to avoid subsequent GETATTR requests. Such caching is write
...
... file by writing data to the local data cache is reflected immediately
in the size as seen on the client without this change being
immediately reflected on the server. Normally such changes are not
propagated directly to the server but when the modified data is
...
... The result of local caching of attributes is that the attribute
caches maintained on individual clients will not be coherent.
Changes made in one order on the server may be seen in a different
order on one client ...
... clients will not be coherent.
Changes made in one order on the server may be seen in a different
order on one client and in a third order on a different client.
...
... Changes made in one order on the server may be seen in a different
order on one client and in a third order on a different client.
The typical filesystem application programming interfaces ...
...
o All attributes for a given file (per-fsid attributes excepted) are
cached as a unit at the client so that no non-serializability can
arise within the context of a single file.
...
... context of a single file.
o An upper time boundary is maintained on how long a client cache
entry can be kept without being refreshed from the server.
...
... modifying operation with a GETATTR operation and then using the
results of the GETATTR to update the client's cached attributes.
Note that if the full set of attributes ...
... 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
attributes obtained via GETATTR.
...
... attributes obtained via GETATTR.
A client may validate its cached version of attributes for a file by
...
... semantics do not update access time when a file is modified by the
write system call. Therefore, the client that wants a current
time_access value should fetch it with change during the attribute
cache ...
... update its cached time_access.
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,
the client MUST NOT maintain a cache of modified attributes.
Instead, attribute changes are immediately sent to the server.
...
... 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
object, whether it is a regular file, directory, or symbolic link,
...
... object, whether it is a regular file, directory, or symbolic link,
the client SHOULD NOT update the time_access attribute (via SETATTR
or a small READ or READDIR request) on the server with each read that
...
... performance benefits of caching content, especially since an explicit
SETATTR of time_access may alter the change attribute on the server.
If the change attribute changes, clients that are caching the content
will think the content has changed, and will re-read unmodified data
from the server. Nor is the client ...
... clients that are caching the content
will think the content has changed, and will re-read unmodified data
from the server. Nor is the client encouraged to maintain a modified
version of time_access in its cache ...
... version of time_access in its cache, since this would mean that the
client will either eventually have to write the access time to the
server with bad performance effects, or it would never update ...
... 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 time.
...
... updated on reads or updates to the file via memory access (regardless
whether the file is local file or is being access remotely). A
client or server MAY fail to update attributes of a file that is
being accessed via memory mapped I/O. This has several implications:
...
...
o If there is an application on the server that has memory mapped a
file that a client is also accessing, the client may not be able
to get a consistent value of the change attribute to determine
...
... o If there is an application on the server that has memory mapped a
file that a client is also accessing, the client may not be able
to get a consistent value of the change attribute to determine
whether its cache ...
... instead is just being read by an application via the memory mapped
interface, the client will not see an updated time_access
attribute. However, in many operating environments, neither will
any process running on the server. Thus NFS ...
... attribute. However, in many operating environments, neither will
any process running on the server. Thus NFS clients are at no
disadvantage with respect to local processes.
...
... disadvantage with respect to local processes.
o If there is another client that is memory mapping the file, and if
that client is holding a write delegation ...
... o If there is another client that is memory mapping the file, and if
that client is holding a write delegation, the same set of issues
as discussed in the previous two bullet items apply. So, when a
...
... delegation, the same set of issues
as discussed in the previous two bullet items apply. So, when a
server does a CB_GETATTR to a file that the client has modified in
its cache, the response from CB_GETATTR will not necessarily be
...
... its cache, the response from CB_GETATTR will not necessarily be
accurate. As discussed earlier, the client's obligation is to
report that the file has been modified since the delegation was
...
... granted, not whether it has been modified again between successive
CB_GETATTR calls, and the server MUST assume that any file the
client has modified in cache has been modified again between
successive CB_GETATTR calls. Depending on the nature of the
...
... cache has been modified again between
successive CB_GETATTR calls. Depending on the nature of the
client's memory management system, this weak obligation may not be
possible. A client ...
... client's memory management system, this weak obligation may not be
possible. A client MAY return stale information in CB_GETATTR
whenever the file is memory mapped.
...
... o The mixture of memory mapping and file locking on the same file is
problematic. Consider the following scenario, where the page size
on each client is 8192 bytes.
- Client ...
... Client A memory maps first page (8192 bytes) of file X
- Client B memory maps first page (8192 bytes) of file X
- Client ...
... Client B memory maps first page (8192 bytes) of file X
- Client A write locks first 4096 bytes
- Client ...
... Client B write locks second 4096 bytes
- Client A, via a STORE instruction modifies part of its locked
region.
...
... its locked region.
Here the challenge is for each client to resynchronize to get a
correct view of the first page. In many operating environments, the
virtual memory management ...
... correct view of the first page. In many operating environments, the
virtual memory management systems on each client only know a page is
modified, not that a subset of the page corresponding to the
respective lock regions has been modified. So it is not possible for
...
... modified, not that a subset of the page corresponding to the
respective lock regions has been modified. So it is not possible for
each client to do the right thing, which is to only write to the
server that portion of the page that is locked. For example, if
client ...
... client to do the right thing, which is to only write to the
server 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
page, client ...
... server 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
page, client A's data is lost.
...
... client A simply writes out the page, and then client B writes out the
page, client A's data is lost.
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 issue the STORE
instructions, the resulting page faults require a record lock on the
...
... instructions, the resulting page faults require a record lock on the
entire page. Each client then tries to extend their locked range to
the entire page, which results in a deadlock.
...
... difficult at best.
If a client is locking the entire memory mapped file, there is no
problem with advisory or mandatory record locking, at least until the
client ...
... client is locking the entire memory mapped file, there is no
problem with advisory or mandatory record locking, at least until the
client unlocks a region in the middle of the file.
Given the above issues the following are permitted:
...
... Given the above issues the following are permitted:
- Clients and servers MAY deny memory mapping a file they know there
are record locks for.
...
... are record locks for.
- Clients and servers MAY deny a record lock on a file they know is
memory mapped.
...
... memory mapped.
- A client MAY deny memory mapping a file that it knows requires
mandatory locking for I/O. If mandatory locking is enabled after
the file is opened and mapped, the client ...
... client MAY deny memory mapping a file that it knows requires
mandatory locking for I/O. If mandatory locking is enabled after
the file is opened and mapped, the client MAY deny the application
further access to its mapped file.
...
... the cost of subsequent LOOKUP operations. Just as in the case of
attribute caching, inconsistencies may arise among the various client
caches. To mitigate the effects of these inconsistencies and given
...
... context of typical filesystem APIs, an upper time boundary is
maintained on how long a client name cache entry can be kept without
verifying that the entry has not been made invalid by a directory
...
... cache entry can be kept without
verifying that the entry has not been made invalid by a directory
change operation performed by another client.
When a client ...
... client.
When a client is not making changes to a directory for which there
exist name cache entries, the client ...
... client is not making changes to a directory for which there
exist name cache entries, the client needs to periodically fetch
attributes for that directory to ensure that it is not being
modified. After determining that no modification has occurred, the
...
... cache staleness bound.
When a client is making changes to a given directory, it needs to
determine whether there have been changes made to the directory by
other clients ...
... client is making changes to a given directory, it needs to
determine whether there have been changes made to the directory by
other clients. It does this by using the change attribute as
reported before and after the directory operation in the associated
change_info4 value returned for the operation. The server is able to
...
... reported before and after the directory operation in the associated
change_info4 value returned for the operation. The server is able to
communicate to the client whether the change_info4 data is provided
atomically with respect to the directory operation. If the change
values are provided atomically, the client ...
... client whether the change_info4 data is provided
atomically with respect to the directory operation. If the change
values are provided atomically, the client is then able to compare
the pre-operation change value with the change value in the client's
...
... values are provided atomically, the client is then able to compare
the pre-operation change value with the change value in the client's
name cache. If the comparison ...
... cache. If the comparison indicates that the directory was
updated by another client, the name cache associated with the
modified directory is purged from the client ...
... client, the name cache associated with the
modified directory is purged from the client. If the comparison
indicates no modification, the name cache ...
... indicates no modification, the name cache can be updated on the
client to reflect the directory operation and the associated timeout
extended. The post-operation change value needs to be saved as the
basis for future change_info4 comparisons.
...
...
As demonstrated by the scenario above, name caching requires that the
client revalidate name cache data by inspecting the change attribute
of a directory at the point when the name cache ...
... update the change attribute for
directories when the contents of the corresponding directory is
modified. For a client to use the change_info4 information
appropriately and correctly, the server must report the pre and post
operation change attribute values atomically. When the server is
...
... to the directory operation, the server must indicate that fact in the
change_info4 return value. When the information is not atomically
reported, the client should not assume that other clients have not
changed the directory.
...
... change_info4 return value. When the information is not atomically
reported, the client should not assume that other clients have not
changed the directory.
...
... The results of READDIR operations may be used to avoid subsequent
READDIR operations. Just as in the cases of attribute and name
caching, inconsistencies may arise among the various client caches.
To mitigate the effects of these inconsistencies, and given the
...
... time a directory cache entry is considered valid before the client
must revalidate the cached information.
...
...
The revalidation technique parallels that discussed in the case of
name caching. When the client is not changing the directory in
question, checking the change attribute of the directory with GETATTR
is adequate. The lifetime ...
... lifetime of the cache entry can be extended at
these checkpoints. When a client is modifying the directory, the
client needs to use the change_info4 data to determine whether there
...
... these checkpoints. When a client is modifying the directory, the
client needs to use the change_info4 data to determine whether there
are other clients modifying the directory. If it is determined that
...
... client needs to use the change_info4 data to determine whether there
are other clients modifying the directory. If it is determined that
no other client modifications are occurring, the client ...
... are other clients modifying the directory. If it is determined that
no other client modifications are occurring, the client may update
...
... clients modifying the directory. If it is determined that
no other client modifications are occurring, the client may update
its directory cache ...
...
As demonstrated previously, directory caching requires that the
client revalidate directory cache data by inspecting the change
attribute of a directory at the point when the directory was cached.
...
... update the change attribute for
directories when the contents of the corresponding directory is
modified. For a client to use the change_info4 information
appropriately and correctly, the server must report the pre and post
operation change attribute values atomically. When the server is
...
... to the directory operation, the server must indicate that fact in the
change_info4 return value. When the information is not atomically
reported, the client should not assume that other clients have not
changed the directory.
...
... change_info4 return value. When the information is not atomically
reported, the client should not assume that other clients have not
changed the directory.
...
... encoding of the minor version being
requested by the client.
The following items represent the basic rules ...
...
Specifying an operation as "mandatory to not implement" is
equivalent to obsoleting an operation. For the client, it means
that the operation should not be sent to the server. For the
server, an NFS ...
... or recommended to mandatory.
11. A client and server that support minor version X must support
minor versions ...
... feature as mandatory.
13. A client MUST NOT attempt to use a stateid, filehandle, or
similar returned object from the COMPOUND procedure with minor
version ...
... internationalization, or I18N, is with respect to file names and
other strings as used within the protocol. The choice of string
representation must allow reasonable name/string access to clients
which use various languages. The UTF-8 encoding ...
... processing utf8str_cs strings, and the NFS version 4 client MUST
assume Table B.2 (in addition to Table B.1) are being used.
...
... later revision of this specification may specify a particular
normalization form. Therefore, the server and client can expect that
they may receive unnormalized characters within protocol requests and
responses. If the operating environment requires normalization ...
... the implementation must normalize utf8str_cs strings within the
protocol before presenting the information to an application (at the
client) or local filesystem (at the server).
...
...
Where the client sends an invalid UTF-8 string, the server should
return an NFS4ERR_INVAL error. This includes cases in which
...
...
NFS4ERR_CLID_INUSE The SETCLIENTID operation has found that a
client id is already in use by another client.
...
... NFS4ERR_CLID_INUSE The SETCLIENTID operation has found that a
client id is already in use by another client.
NFS4ERR_DEADLOCK The server has been able to determine a file
...
... NFS4ERR_DELAY The server initiated the request, but was not
able to complete it in a timely fashion. The
client should wait and then try the request
with a new RPC transaction ...
... migrated. In this case, the server should start
the immigration process and respond to client
with this error. This error may also occur
when a necessary delegation ...
...
NFS4ERR_DENIED An attempt to lock a file is denied. Since
this may be a temporary condition, the client
is encouraged to retry the lock request until
the lock is accepted.
...
... NFS4ERR_MOVED The filesystem which contains the current
filehandle object has been relocated or
migrated to another server. The client may
obtain the new filesystem location by obtaining
the "fs_locations" attribute for the current
...
... the server can not guarantee that conflicting
state has not been provided to another client.
NFS4ERR_NOSPC No space left on device. The operation would
...
... NFS4ERR_NOT_SAME This error is returned by the VERIFY operation
to signify that the attributes compared were
not the same as provided in the client's
request.
...
... used.
NFS4ERR_OPENMODE The client attempted a READ, WRITE, LOCK or
SETATTR operation not sanctioned by the stateid
passed (e.g., writing to a file opened only for
...
... the operation.
NFS4ERR_RECLAIM_BAD The reclaim provided by the client does not
match any of the server's state consistency ...
...
NFS4ERR_RECLAIM_CONFLICT
The reclaim provided by the client has
encountered a conflict and can not be provided.
Potentially indicates a misbehaving client ...
... by the client has
encountered a conflict and can not be provided.
Potentially indicates a misbehaving client.
NFS4ERR_RESOURCE For the processing of the COMPOUND procedure,
...
... NFS4ERR_SAME This error is returned by the NVERIFY operation
to signify that the attributes compared were
the same as provided in the client's request.
NFS4ERR_SERVERFAULT An error occurred on the server which does not
...
... NFS version 4 protocol
error values. The client should translate this
into an appropriate error. UNIX clients ...
... client should translate this
into an appropriate error. UNIX clients may
choose to translate this to EIO.
...
...
NFS4ERR_WRONGSEC 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 retry the
...
... encapsulated within the COMPOUND procedure. This requires that the
client combine one or more of the NFS version 4 operations into a
...
... single request.
The NFS4_CALLBACK program is used to provide server to client
signaling and is constructed in a similar fashion as the NFS ...
... NFS4_CALLBACK program. There is no predefined RPC program number for
the NFS4_CALLBACK program. It is up to the client to specify a
program number in the "transient" program range. The program and
...
... range. The program and
port number of the NFS4_CALLBACK program are provided by the client
as part of the SETCLIENTID/SETCLIENTID_CONFIRM sequence. The program
and port ...
... port can be changed by another SETCLIENTID/SETCLIENTID_CONFIRM
sequence, and it is possible to use the sequence to change them
within a client incarnation without removing relevant leased client
...
... performance within high latency networks. The client can avoid
cumulative latency of multiple RPCs by combining multiple dependent
...
... latency of multiple RPCs by combining multiple dependent
operations into a single COMPOUND procedure. A compound operation
may provide for protocol simplification by allowing the client to
combine basic procedures into a single request that is customized for
the client ...
... client to
combine basic procedures into a single request that is customized for
the client's environment.
The CB_COMPOUND procedure precisely parallels the features of
...
... COMPOUND requests that the server receives.
It is the client's responsibility for recovering from any partially
completed COMPOUND procedure. Partially completed COMPOUND
procedures may occur at any point due to errors such as
...
... valid operation string. Further, a server reboot which
occurs in the middle of processing a COMPOUND procedure may leave the
client with the difficult task of determining how far COMPOUND
processing has proceeded. Therefore, the client should avoid overly
...
... client with the difficult task of determining how far COMPOUND
processing has proceeded. Therefore, the client should avoid overly
complex COMPOUND procedures in the event of the failure of an
operation within the procedure.
...
... version 4 operations that modify the filesystem are synchronous.
When an operation is successfully completed at the server, the client
can depend that any data associated with the request is now on stable
storage (the one exception is in the case of the file data in a WRITE
...
... This implies that any previous operations within the same compound
request are also reflected in stable storage. This behavior enables
the client's ability to recover from a partially executed compound
request which may resulted from the failure of the server. For
example, if a compound request contains operations A and B and the
...
... request which may resulted from the failure of the server. For
example, if a compound request contains operations A and B and the
server is unable to send a response to the client, depending on the
progress the server made in servicing the request the result of both
operations may be reflected in stable storage or just operation A may
...
... assumes that all previous operations within the COMPOUND sequence
have been evaluated successfully. The results for all of the
evaluated operations must be returned to the client.
The server will generally choose between two methods ...
... The server will generally choose between two methods of decoding the
client's request. The first would be the traditional one-pass XDR
decode, in which decoding of the entire COMPOUND precedes execution
...
... default value for this field is 0 (zero). This field will be
used by future minor versions such that the client can communicate to
the server what minor version is being requested. If the server
...
... minorversion field has a value of 0 (zero), an error of
NFS4ERR_OP_ILLEGAL, as described in the next paragraph, is returned
to the client. If an operation array contains an operation 2 and the
minorversion field is non-zero and the server does not support the
...
...
Since an error of any type may occur after only a portion of the
operations have been evaluated, the client must be prepared to
recover from any failure. If the source of an NFS4ERR_RESOURCE error
was a complex or lengthy set of operations, it is likely that if the
...
... was a complex or lengthy set of operations, it is likely that if the
number of operations were reduced the server would be able to
evaluate them successfully. Therefore, the client is responsible for
dealing with this type of complexity in recovery.
...
... RPC request, has with respect to the file system
object specified by the current filehandle. The client encodes the
set of access rights that are to be checked in the bit mask ...
...
Note that the supported field will contain only as many values as
were originally sent in the arguments. For example, if the client
sends an ACCESS operation with only the ACCESS4_READ value set and
the server supports this value, the server will return only
...
... IMPLEMENTATION
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 control restrictions. It is also
possible that the server may not be in the same ID space as the
client. In these cases (and perhaps others), the client can not
reliably perform an access check with only current file attributes.
...
... possible that the server may not be in the same ID space as the
client. In these cases (and perhaps others), the client can not
reliably perform an access check with only current file attributes.
...
... NFS version 4
protocol, the client can ask the server to indicate whether or not
one or more classes of operations are permitted. The ACCESS
...
... one or more classes of operations are permitted. The ACCESS
operation is provided to allow clients to check before doing a series
of operations which will result in an access failure. The OPEN
...
... operation provides a point where the server can verify access to the
file object and method to return that information to the client. The
ACCESS operation is still useful for directory operations or for use
in the case the UNIX ...
... in the case the UNIX API "access" is used on the client.
The information returned by the server ...
... revoke access permission at any time.
The client should use the effective credentials of the user to build
the authentication information ...
... determined will have the ACCESS4_DELETE value set to 0. This
indicates to the client that the server was unable to check that
particular access right. The ACCESS4_DELETE ...
... associated with other OPENs is not affected.
If record locks are held, the client SHOULD release all locks before
issuing a CLOSE. The server MAY free all outstanding locks on CLOSE
but some servers may not support the CLOSE of a file that still has
...
...
Even though CLOSE returns a stateid, this stateid is not useful to
the client and should be treated as deprecated. CLOSE "shuts down"
the state associated with all OPENs for the file by a single
...
... verifier upon successful completion of the
COMMIT. The write verifier is used by the client to determine if the
server has restarted or rebooted between the initial WRITE(s) and the
COMMIT. The client ...
... by the client to determine if the
server has restarted or rebooted between the initial WRITE(s) and the
COMMIT. The client does this by comparing the write verifier
returned from the initial writes and the verifier ...
... state with the
disk (file data and metadata is flushed to disk or stable storage).
COMMIT performs the same operation for a client, flushing any
unsynchronized data and metadata on the server to the server's disk
or stable storage for the specified file. Like fsync(2), it may be
...
... unless there has been an unexpected error.
COMMIT differs from fsync(2) in that it is possible for the client to
flush a range of the file (most likely triggered by a buffer ...
... range of the file (most likely triggered by a buffer-
reclamation scheme on the client before file has been completely
written).
...
... during the last server failure.
The client implementation of COMMIT is a little more complex. There
are two reasons for wanting to commit a client buffer ...
... The client implementation of COMMIT is a little more complex. There
are two reasons for wanting to commit a client buffer to stable
storage. The first is that the client wants ...
... client buffer to stable
storage. The first is that the client wants to reuse a buffer. In
this case, the offset and count of the buffer ...
... file. It then returns the status of the flush and the write
verifier. The other 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 ...
... client to generate a COMMIT is
for a full 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 data, do the COMMIT operation with an offset of 0 and
...
...
After a buffer is written by the client with the stable parameter set
to UNSTABLE4, the buffer must be considered as modified by the client ...
... by the client with the stable parameter set
to UNSTABLE4, the buffer must be considered as modified by the client
until the buffer has either been flushed via a COMMIT operation or
...
... verifier that is different than previously
returned by the server, the client will need to retransmit all of the
buffers containing uncommitted cached data to the server. How this
...
... valid for the object type. When the operation is successful, the
server will return to the client an attribute mask signifying which
attributes were successfully set for the object.
...
... operation too.
Conversely, it is possible the client will specify in createattrs an
owner attribute or group attribute or ACL ...
... IMPLEMENTATION
If the client desires to set attribute values after the create, a
SETATTR operation can be added to the COMPOUND request so that the
...
...
Purges all of the delegations awaiting recovery for a given client.
This is useful for clients which do not commit delegation ...
... delegations awaiting recovery for a given client.
This is useful for clients which do not commit delegation information
to stable storage to indicate that conflicting requests need not be
...
... delegation information.
This operation should be used by clients that record delegation
information on stable storage on the client ...
... clients that record delegation
information on stable storage on the client. In this case,
DELEGPURGE should be issued immediately after doing delegation
...
... delegation
recovery on all delegations known to the client. Doing so will
notify the server that no additional delegations for the client ...
... client. Doing so will
notify the server that no additional delegations for the client will
be recovered allowing it to free resources, and avoid delaying other
clients ...
... client will
be recovered allowing it to free resources, and avoid delaying other
clients who make requests that conflict with the unrecovered
delegations. The set of delegations ...
... delegations. The set of delegations known to the server and the
client may be different. The reason for this is that a client may
fail after making a request which resulted in delegation ...
... delegations known to the server and the
client may be different. The reason for this is that a client may
fail after making a request which resulted in delegation but before
...
... fail after making a request which resulted in delegation but before
it received the results and committed them to the client's stable
storage.
...
... Delegations may be returned when recalled or voluntarily (i.e.,
before the server has recalled them). In either case the client must
properly propagate state changed under the context ...
...
The GETATTR operation will obtain attributes for the filesystem
object specified by the current filehandle. The client sets a bit in
the bitmap argument for each attribute value that it would like the
...
... first.
The server must return a value for each attribute that the client
requests if the attribute is supported by the server. If the server
does not support an attribute or cannot approximate a useful value
...
... CREATE
do not automatically return the new filehandle as a result. For
instance, if a client needs to lookup a directory entry and obtain
its filehandle then the following request is needed.
...
... Some servers may only support locking for byte offsets that fit
within 32 bits. If the client specifies a range that includes a byte
beyond the last byte offset of the 32-bit ...
... not.
When the client makes a lock request that corresponds to a range that
the lockowner has locked already (with the same or different lock
...
... semantics), the server will
return the error NFS4ERR_LOCK_RANGE. In that case, the client may
return an error, or it may emulate the required operations, using
only LOCK for ranges ...
... (specifying an exactly-matching range and type). Similarly, when the
client makes a lock request that amounts to upgrading (changing from
a read lock to a write lock) or downgrading (changing from write lock
to a read lock) an existing record lock, and the server does not
...
... Such operations may not perfectly reflect the required semantics in
the face of conflicting lock requests from other clients.
The locker argument specifies the lock_owner that is associated with
...
...
LOCKT uses a lock_owner4 rather a stateid4, as is used in 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 a stateid may not be
available.
...
... range checking, NFS4ERR_LOCK_RANGE may be returned.. In
the event that it returns NFS4_OK, clients may do a LOCK and receive
NFS4ERR_LOCK_RANGE on the LOCK request because of the flexibility
...
...
The LOCKU operation unlocks the record lock specified by the
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
accept any legal value for locktype. Any legal value for locktype has
...
... these cases, allowed by POSIX locking semantics, a client receiving
this error, should if it desires support for such operations,
...
...
If the component cannot be evaluated either because it does not exist
or because the client does not have permission to evaluate the
component, then an error will be returned and the current filehandle
will be unchanged.
...
... IMPLEMENTATION
If the client wants to achieve the effect of a multi-component
lookup, it may construct a COMPOUND request such as (and obtain each
...
... versions in allowing LOOKUP requests to cross mountpoints on the
server. The client can detect a mountpoint crossing by comparing 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
mountpoint crossing will need to mount the server's filesystem. This
needs to be done to maintain the file object identity ...
... should provide a pseudo-filesystem into which the exported
filesystems can be integrated, so that clients can browse the
server's name space. The clients ...
... clients can browse the
server's name space. The clients' view of a pseudo filesystem will
be limited to paths that lead to exported filesystems.
...
...
Note that this operation does not follow symbolic links. The client
is responsible for all parsing of filenames including filenames that
are modified by symbolic links ...
... operation and the server does not support that attribute for the
filesystem object, the error NFS4ERR_ATTRNOTSUPP is returned to the
client.
When the attribute rdattr_error or any write-only attribute (e.g.,
...
... When the attribute rdattr_error or any write-only attribute (e.g.,
time_modify_set) is specified, the error NFS4ERR_INVAL is returned to
the client.
ERRORS
...
... /* Right to file based on a delegation granted to a previous boot
* instance of the client. File is specified by name.
*/
case CLAIM_DELEGATE_PREV:
...
... (CLAIM_PREVIOUS) */
nfs_space_limit4 space_limit; /* Defines condition that
the client must check to
determine whether the
file needs to be flushed
...
... };
WARNING TO CLIENT IMPLEMENTORS
OPEN resembles LOOKUP ...
... OPEN resembles LOOKUP in that it generates a filehandle for the
client to use. Unlike LOOKUP though, OPEN creates server state ...
... creates server state on
the filehandle. In normal circumstances, the client can only release
this state with a CLOSE operation. CLOSE uses the current filehandle
...
... this state with a CLOSE operation. CLOSE uses the current filehandle
to determine which file to close. Therefore the client MUST follow
every OPEN operation with a GETFH operation in the same COMPOUND
procedure. This will supply the client ...
... client MUST follow
every OPEN operation with a GETFH operation in the same COMPOUND
procedure. This will supply the client with the filehandle such that
CLOSE can be used appropriately.
...
... because the server may maintain the state indefinitely as long as
another client does not attempt to make a conflicting access to the
same file.
...
... creation is desired, specification of the method of creation is
provided by the openhow parameter. The client has the choice of
three creation methods: UNCHECKED, GUARDED, or EXCLUSIVE.
...
...
each of these cases (UNCHECKED and GUARDED) where the operation is
successful, the server will return to the client an attribute mask
signifying which attributes were successfully set for the object.
...
... verifier with the object. If the object does
exist and the stored verifier matches the client provided verifier,
the server uses the existing object as the newly created ...
... reservation capability
with the use of the share_access and share_deny fields of the OPEN
arguments. The client specifies at OPEN the required share_access
and share_deny modes. For clients that do not directly support
...
... arguments. The client specifies at OPEN the required share_access
and share_deny modes. For clients that do not directly support
SHAREs (i.e., UNIX), the expected deny value is DENY ...
... reservation that conflicts with
the OPEN request, the server returns the error NFS4ERR_SHARE_DENIED.
For a complete SHARE request, the client must provide values for the
owner and seqid fields for the OPEN argument. For additional
discussion ...
... Reservations'.
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 "claim" field of the OPEN argument is used to specify the file to
be opened and the state information which the client claims to
possess. There are four basic claim types which cover the various
situations for an OPEN. They are as follows:
...
... request and there is no previous state
associate with the file for the client.
CLAIM_PREVIOUS
...
...
CLAIM_PREVIOUS
The client is claiming basic OPEN state
for a file that was held previous to a
...
... server reboot. Generally used when a
server is returning persistent
filehandles; the client may not have the
file name to reclaim the OPEN.
...
... client is claiming a delegation
granted to a previous client instance;
used after the client reboots. The
...
... granted to a previous client instance;
used after the client reboots. The
server MAY support CLAIM_DELEGATE_PREV.
If it does support CLAIM_DELEGATE_PREV,
...
... 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 described in the section Open Delegation. Note that delegation ...
... Delegation. Note that delegation is
up to the server to decide. The client should never assume that
delegation will or will not be granted in a particular instance. It
...
... information governing how the open file is to be handled.
OPEN4_RESULT_CONFIRM indicates that the client MUST execute an
OPEN_CONFIRM operation before using the open file.
OPEN4_RESULT_LOCKTYPE_POSIX ...
... POSIX indicates the server's file locking
behavior supports the complete set of Posix locking techniques. From
this the client can choose to manage file locking state in a way to
handle a mis-match of file locking management ...
... creation. Exclusive create is invoked when the how parameter is
EXCLUSIVE. In this case, the client provides a verifier that can
reasonably be expected to be unique. A combination of a client
identifier ...
... client provides a verifier that can
reasonably be expected to be unique. A combination of a client
identifier, perhaps the client network address ...
... verifier that can
reasonably be expected to be unique. A combination of a client
identifier, perhaps the client network address, and a unique number
...
... network address, and a unique number
generated by the client, perhaps the RPC transaction identifier ...
... NFS4ERR_EXIST.
Once the client has performed a successful exclusive create, it must
issue a SETATTR to set the correct object attributes ...
... NFS4ERR_EXIST, even though the create was performed successfully.
The client would use this behavior in the case that the application
has not requested an exclusive create but has asked to have the file
...
... has not requested an exclusive create but has asked to have the file
truncated when the file is opened. In the case of the client timing
out and retransmitting the create request, the client ...
... client timing
out and retransmitting the create request, the client can use GUARDED
to prevent against a sequence like: create, write, create ...
... (retransmitted) from occurring.
For SHARE reservations, the client must specify a value for
share_access that is one of READ, WRITE, or BOTH. For share_deny,
the client ...
... client must specify a value for
share_access that is one of READ, WRITE, or BOTH. For share_deny,
the client must specify one of NONE, READ, WRITE, or BOTH. If the
client fails to do this, the server must return NFS4ERR_INVAL.
...
... the client must specify one of NONE, READ, WRITE, or BOTH. If the
client fails to do this, the server must return NFS4ERR_INVAL.
Based on the share_access value (READ, WRITE, or BOTH) the client ...
... client fails to do this, the server must return NFS4ERR_INVAL.
Based on the share_access value (READ, WRITE, or BOTH) the client
should check that the requester has the proper access rights to
...
... of applying the ACL access rules to the file for the current
requester. However, just as with the ACCESS operation, the client
should not attempt to second-guess the server's decisions, as access
rights may change and may be subject ...
... If the component provided to OPEN is a symbolic link, the error
NFS4ERR_SYMLINK will be returned to the client. If the current
filehandle is not a directory, the error NFS4ERR_NOTDIR will be
returned.
...
... NF4NAMEDATTR.
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
of FALSE for createdir to determine if any named attributes exist for
the object. If none exist, then NFS4ERR_NOENT will be returned. If
...
... If the server does not support named attributes for the current
filehandle, an error of NFS4ERR_NOTSUPP will be returned to the
client.
ERRORS
...
...
This operation is used to confirm the sequence id usage for the first
time that a open_owner is used by a client. The stateid returned
from the OPEN operation is used as the argument for this operation
along with the next sequence id for the open_owner. The sequence id
...
... passed to the OPEN operation from which the open_confirm value was
obtained. If the server receives an unexpected sequence id with
respect to the original open, then the server assumes that the client
will not confirm the original OPEN and all state associated with the
...
... IMPLEMENTATION
A given client might generate many open_owner4 data structures for a
given clientid. The client ...
... client might generate many open_owner4 data structures for a
given clientid. The client will periodically either dispose of its
open_owner4s or stop using them for indefinite periods of time. The
latter situation is why the NFS ...
... data structures.
In the case that a client issues an OPEN operation and the server no
longer has a record of the open_owner4, the server needs to ensure
...
... maintain a single bit that notes whether any open_owner4 (for any
client) has been disposed of.
The server must hold unconfirmed OPEN state ...
... The server must hold unconfirmed OPEN state until one of three events
occur. First, the client sends an OPEN_CONFIRM request with the
appropriate sequence id and stateid within the lease period. In this
case, the OPEN state ...
... open_owner4 on the server is fully established.
Second, the client sends another OPEN request with a sequence id that
is incorrect for the open_owner4 (out of sequence). In this case,
the server assumes the second OPEN request is valid ...
... While there is a potential for a denial of service attack on the
client, it is mitigated if the client and server require the use of a
security ...
... denial of service attack on the
client, it is mitigated if the client and server require the use of a
security flavor based on Kerberos ...
... With the NFS version 2 and 3 public filehandle, the client is able to
specify whether the path name provided in the LOOKUP should be
...
... version 4. Therefore,
the client is responsible for constructing its request such that the
use of either PUTROOTFH or PUTPUBFH are used to signify absolute or
relative evaluation of an NFS ...
... framework as NFS versions 2 and 3. Clients should therefore use the
security negotiation mechanisms described in this RFC.
...
... current filehandle.
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 0 (zero) means
...
... subject to access permissions checking.
If the client specifies a count value of 0 (zero), the READ succeeds
and returns 0 (zero) bytes of data again subject to access
...
... subject to access
permissions checking. The server may choose to return fewer bytes
than specified by the client. The client needs to check for this
condition and handle the condition appropriately.
...
... permissions checking. The server may choose to return fewer bytes
than specified by the client. The client needs to check for this
condition and handle the condition appropriately.
...
... valid and to update lease timeouts for
the client.
If the read ended at the end-of-file (formally, in a correctly formed
...
...
If the current filehandle is not a regular file, an error will be
returned to the client. In the case the current filehandle
represents a directory, NFS4ERR_ISDIR is return; otherwise,
NFS4ERR_INVAL is returned.
...
... It is possible for the server to return fewer than count bytes of
data. If the server returns less than the count requested and eof is
set to FALSE, the client should issue another READ to get the
remaining data. A server may return less data than requested under
several circumstances. The file may have been truncated by another
...
... remaining data. A server may return less data than requested under
several circumstances. The file may have been truncated by another
client or perhaps on the server itself, changing the file size from
what the requesting client believes to be the case. This would
...
... client or perhaps on the server itself, changing the file size from
what the requesting client believes to be the case. This would
reduce the actual amount of data available to the client. It is
...
... what the requesting client believes to be the case. This would
reduce the actual amount of data available to the client. It is
possible that the server may back off the transfer size and reduce
the read request return. Server resource exhaustion may also occur
...
... corresponding to the data to be read from file is write locked by an
owner not associated the stateid, the server will return the
NFS4ERR_LOCKED error. The client should try to get the appropriate
read record lock via the LOCK operation before re-attempting the
READ. When the READ completes, the client ...
... client should try to get the appropriate
read record lock via the LOCK operation before re-attempting the
READ. When the READ completes, the client should release the record
lock via LOCKU.
...
...
The READDIR operation retrieves a variable number of entries from a
filesystem directory and returns client requested attributes for each
entry along with information to allow the client to request
...
... filesystem directory and returns client requested attributes for each
entry along with information to allow the client to request
additional directory entries in a subsequent READDIR.
...
... cookie is used to start reading at the beginning of the
directory. For subsequent READDIR requests, the client specifies a
cookie value that is provided by the server ...
... overhead. The server may return less data. If the server is unable
to return a single directory entry within the maxcount limit, the
error NFS4ERR_TOOSMALL will be returned to the client.
Finally, attr_request represents the list of attributes to be
...
... "bookmark" for the directory entry. As mentioned, this cookie 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
...
... cookie is similar in concept to a
READ offset but should not be interpreted as such by the client.
Ideally, the cookie value should not change if the directory is
...
... Ideally, the cookie value should not change if the directory is
modified since the client may be caching these values.
In some cases, the server may encounter an error while obtaining the
...
... the entire READDIR operation, the server can instead return the
attribute 'fattr4_rdattr_error'. With this, the server is able to
communicate the failure to the client and not fail the entire
operation in the instance of what might be a transient failure.
Obviously, the client ...
... client and not fail the entire
operation in the instance of what might be a transient failure.
Obviously, the client must request the fattr4_rdattr_error attribute
for this method to work properly. If the client ...
... client must request the fattr4_rdattr_error attribute
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
entire READDIR operation.
...
... have special meaning and in other environments, they may not. If the
server supports these special entries within a directory, they should
not be returned to the client as part of the READDIR response. To
enable some client environments, the cookie ...
... not be returned to the client as part of the READDIR response. To
enable some client environments, the cookie values of 0, 1, and 2 are
to be considered reserved. Note that the UNIX ...
... cookie values of 0, 1, and 2 are
to be considered reserved. Note that the UNIX client will use these
values when combining the server's response and local representations
to enable a fully formed UNIX ...
...
The server's filesystem directory representations can differ greatly.
A client's programming interfaces may also be bound to the local
operating environment in a way that does not translate well into the
...
... NFS protocol. Therefore the use of the dircount and maxcount fields
are provided to allow the client the ability to provide guidelines to
the server. If the client is aggressive about attribute collection
...
... are provided to allow the client the ability to provide guidelines to
the server. If the client is aggressive about attribute collection
during a READDIR, the server has an idea of how to limit the encoded
response. The dircount field provides a hint ...
... cookie/cookieverf pair. The server should make every effort to avoid
this condition since the application at the client may not be able to
properly handle this type of failure.
...
... properly handle this type of failure.
The use of the cookieverf will also protect the client from using
READDIR cookie values that may be stale. For example, if the file
system ...
... cookie values to service READDIR as the previous server
used. With the client providing the cookieverf, the server is able
to provide the appropriate response to the client. This prevents the
...
... used. With the client providing the cookieverf, the server is able
to provide the appropriate response to the client. This prevents the
case where the server may accept a cookie value but the underlying
...
... case where the server may accept a cookie value but the underlying
directory has changed and the response is invalid from the client's
context of its previous READDIR.
...
... been done with previous versions of the NFS protocol, the client that
requires these entries be present in READDIR responses must fabricate
them.
...
... not necessarily interpreted by the server, just stored in the file.
It is possible for a client implementation to store a path name that
is not meaningful to the server operating system in a symbolic link ...
... operating system in a symbolic link.
A READLINK operation returns the data to the client for
interpretation. If different implementations want to share access to
symbolic links ...
... directory removal and REMOVE for non-directory removal. This allowed
clients to skip checking the file type when being passed a non-
directory delete ...
... NFS version 4
client's entry points from the unlink() and rmdir() system calls
should first check the file type against the types the system call is
...
... The concept of last reference is server specific. However, if the
numlinks field in the previous attributes of the object had the value
1, the client should not rely on referring to the object via a
filehandle. Likewise, the client should not rely on the resources
...
... 1, the client should not rely on referring to the object via a
filehandle. Likewise, the client should not rely on the resources
(disk space, directory entry, and so on) formerly associated with the
object becoming immediately available. Thus, if a client ...
... client should not rely on the resources
(disk space, directory entry, and so on) formerly associated with the
object becoming immediately available. Thus, if a client needs to be
able to continue to access a file after using REMOVE to remove ...
... REMOVE to remove it,
the client should take steps to make sure that the file will still be
accessible. The usual mechanism used is to RENAME the file from its
old name to a new hidden name.
...
... target directory corresponding to
the current filehandle. The operation is required to be atomic to
the client. Source and target directories must reside on the same
filesystem on the server. On success, the current filehandle will
...
... section "Operation 28: REMOVE - Remove Filesystem Object" for client
and server actions whenever a target is removed). If they are not
...
... IMPLEMENTATION
The RENAME operation must be atomic to the client. The statement
"source and target directories must reside on the same filesystem on
...
... DESCRIPTION
The RENEW operation is used by the client to renew leases which it
currently holds at a server. In processing the RENEW request, the
...
... currently holds at a server. In processing the RENEW request, the
server renews all leases associated with the client. The associated
leases are determined by the clientid provided via the SETCLIENTID
operation.
...
... IMPLEMENTATION
When the client holds delegations, it needs to use RENEW to detect
when the server has determined that the callback path is down. When
...
... it returns NFS4ERR_CB_PATH_DOWN, the server MUST renew the lease on
the record locks and share reservations that the client has
established on the server. If for some reason the lock and share
reservation ...
... GSS -- the same mechanism and service that
was used when the client id was established via
SETCLIENTID_CONFIRM.
...
... The result will contain an array which represents the security
mechanisms available, with an order corresponding to server's
preferences, the most preferred being first in the array. The client
is free to pick whatever security mechanism it both desires and
...
...
The SECINFO operation is expected to be used by the NFS client when
the error value of NFS4ERR_WRONGSEC is returned from another NFS ...
... error value of NFS4ERR_WRONGSEC is returned from another NFS
operation. This signifies to the client that the server's security
policy is different from what the client is currently using. At this
...
... operation. This signifies to the client that the server's security
policy is different from what the client is currently using. At this
point, the client is expected to obtain a list of possible security ...
... security
policy is different from what the client is currently using. At this
point, the client is expected to obtain a list of possible security
flavors and choose what best suits its policies.
...
... As mentioned, the server's security policies will determine when a
client request receives NFS4ERR_WRONGSEC. The operations which may
receive this error are: LINK, LOOKUP ...
... security used for the
operation is inappropriate for saved filehandle. With the exception
of READDIR, these operations represent the point at which the client
can instantiate a filehandle into the "current filehandle" at the
server. The filehandle is either provided by the client ...
... client
can instantiate a filehandle into the "current filehandle" at the
server. The filehandle is either provided by the client (PUTFH,
PUTPUBFH, PUTROOTFH) or generated as a result of a name to filehandle
translation (LOOKUP ...
... security policy has not changed.
If the client wants to resolve an error return of NFS4ERR_WRONGSEC,
the following will occur:
...
...
o For LOOKUP and OPEN, the client will use SECINFO with the same
current filehandle and name as provided in the original LOOKUP or
...
...
o For LINK, PUTFH, RENAME, and RESTOREFH, the client will use
SECINFO and provide the parent directory filehandle and object
name which corresponds to the filehandle originally provided by
...
... LINK and RENAME, the SAVEFH.
o For PUTROOTFH and PUTPUBFH, the client will be unable to use the
SECINFO operation since SECINFO requires a current filehandle and
none exist for these two operations. Therefore, the client ...
... client will be unable to use the
SECINFO operation since SECINFO requires a current filehandle and
none exist for these two operations. Therefore, the client must
iterate through the security triples available at the client ...
... client must
iterate through the security triples available at the client and
reattempt the PUTROOTFH or PUTPUBFH operation. In the unfortunate
event none of the MANDATORY security ...
... reattempt the PUTROOTFH or PUTPUBFH operation. In the unfortunate
event none of the MANDATORY security triples are supported by the
client and server, the client SHOULD try using others that support
integrity ...
... event none of the MANDATORY security triples are supported by the
client and server, the client SHOULD try using others that support
integrity. Failing that, the client ...
... client SHOULD try using others that support
integrity. Failing that, the client can try using AUTH_NONE, but
because such forms lack integrity ...
... AUTH_NONE, but
because such forms lack integrity checks, this puts the client at
risk. Nonetheless, the server SHOULD allow the client to use
...
... integrity checks, this puts the client at
risk. Nonetheless, the server SHOULD allow the client to use
whatever security form the client requests ...
... client to use
whatever security form the client requests and the server
supports, since the risks of doing so are on the client.
...
... security form the client requests and the server
supports, since the risks of doing so are on the client.
The READDIR operation will not directly return the NFS4ERR_WRONGSEC
...
... security triple
does not match that of a directory entry. If this is the case and
the client has requested the rdattr_error attribute, the server will
return the NFS4ERR_WRONGSEC error in rdattr_error for the entry.
...
... attribute unless the requester has privilege to do so. If the server
is lenient in this one case of matching owner values, the client
implementation may be simplified in cases of creation of an object
followed by a SETATTR.
...
... current size of the file causes logically zeroed data bytes to be
added to the end of the file. Servers are free to implement this
using holes or actual zero data bytes. Clients should not make any
assumptions regarding a server's implementation of this feature,
beyond that the bytes returned will be zeroed. Servers must support
...
...
Changing the size of a file with SETATTR indirectly changes the
time_modify. A client must account for this as size changes can
result in data deletion.
...
...
The attributes time_access_set and time_modify_set are write-only
attributes constructed as a switched union so the client can direct
the server in setting the time values. If the switched union
specifies SET ...
... the server in setting the time values. If the switched union
specifies SET_TO_CLIENT_TIME4, the client has provided an nfstime4 to
be used for the operation. If the switch ...
... specifies SET_TO_CLIENT_TIME4, the client has provided an nfstime4 to
be used for the operation. If the switch union does not specify
...
... switch union does not specify
SET_TO_CLIENT_TIME4, the server is to use its current time for the
SETATTR operation.
...
... SETATTR operation.
If server and client times differ, programs that compare client time
to file times can break. A time maintenance protocol should be used
...
...
If server and client times differ, programs that compare client time
to file times can break. A time maintenance protocol should be used
to limit client/server ...
... client time
to file times can break. A time maintenance protocol should be used
to limit client/server time skew.
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
whereby a client may specify a request that emulates the
functionality of the SETATTR guard mechanism of NFS version 3 ...
... executing such a request.
If the server does not support an attribute as requested by the
client, the server should return NFS4ERR_ATTRNOTSUPP.
A mask of the attributes actually set is returned by SETATTR in all
...
... cases. That mask must not include attributes bits not requested to
be set by the client, and must be equal to the mask of attributes
requested to be set only if the SETATTR completes without error.
...
... SYNOPSIS
client, callback, callback_ident -> clientid, setclientid_confirm
ARGUMENT
...
... SETCLIENTID4resok resok4;
case NFS4ERR_CLID_INUSE:
clientaddr4 client_using;
default:
void;
...
... DESCRIPTION
The client uses the SETCLIENTID operation to notify the server of its
intention to use a particular client identifier, callback, and
...
... The client uses the SETCLIENTID operation to notify the server of its
intention to use a particular client identifier, callback, and
callback_ident for subsequent requests that entail creating lock,
share reservation ...
...
The callback information provided in this operation will be used if
the client is provided an open delegation at a future point.
Therefore, the client ...
... client is provided an open delegation at a future point.
Therefore, the client must correctly reflect the program and port
numbers for the callback program at the time SETCLIENTID is used.
...
... The callback_ident value is used by the server on the callback. The
client can leverage the callback_ident to eliminate the need for more
than one callback RPC program number, while still being able to
...
... notations. Let:
x be the value of the client.id subfield of the SETCLIENTID4args
structure.
...
... structure.
v be the value of the client.verifier subfield of the
SETCLIENTID4args structure.
...
...
{ v, x, c, k, s }
be a quintuple for a client record. A client record is
confirmed if there has been a SETCLIENTID_CONFIRM operation to
...
... { v, x, c, k, s }
be a quintuple for a client record. A client record is
confirmed if there has been a SETCLIENTID_CONFIRM operation to
confirm it. Otherwise it is unconfirmed. An unconfirmed
...
... returns the result cached in the DRC. The server does NOT remove
client state (locks, shares, delegations) nor does it modify any
...
... state (locks, shares, delegations) nor does it modify any
recorded callback and callback_ident information for client { x }.
For any DRC miss, the server takes the client id ...
... client { x }.
For any DRC miss, the server takes the client id string x, and
searches for client records for x that the server may have
...
... For any DRC miss, the server takes the client id string x, and
searches for client records for x that the server may have
recorded from previous SETCLIENTID calls. For any confirmed record
with the same id string x, if the recorded principal ...
... discussion, the remaining description of the
processing assumes that there was a DRC miss, and that where the
server has previously recorded a confirmed record for client x,
the aforementioned principal check has successfully passed.
...
...
The server returns { c, t }. It is indeed returning the old
clientid4 value c, because the client apparently only wants to
update callback value k to value l. It's possible this request is
...
... The server awaits confirmation of { d, k } via SETCLIENTID_CONFIRM
{ d, t }. The server does NOT remove client
(lock/share/delegation) state ...
... DESCRIPTION
This operation is used by the client to confirm the results from a
previous call to SETCLIENTID. The client provides the server
...
... This operation is used by the client to confirm the results from a
previous call to SETCLIENTID. The client provides the server
supplied (from a SETCLIENTID response) clientid. The server responds
with a simple status of success or failure.
...
... IMPLEMENTATION
The client must use the SETCLIENTID_CONFIRM operation to confirm the
following two distinct cases:
...
... following two distinct cases:
o The client's use of a new shorthand client identifier (as returned
from the server in the response to SETCLIENTID), a new callback
...
...
o The client's use of a new shorthand client identifier (as returned
from the server in the response to SETCLIENTID), a new callback
value (as specified in the arguments to SETCLIENTID) and a new
...
... value (as specified in the arguments to SETCLIENTID) and a new
callback_ident (as specified in the arguments to SETCLIENTID)
value. The client's use of SETCLIENTID_CONFIRM in this case also
confirms the removal of any of the client's previous relevant
...
... value. The client's use of SETCLIENTID_CONFIRM in this case also
confirms the removal of any of the client's previous relevant
leased state. Relevant leased client ...
... client's previous relevant
leased state. Relevant leased client state includes record locks,
share reservations, and where the server does not support the
...
... remove delegations for this client; relevant leased client state
would then just include record locks and share reservations.
...
... would then just include record locks and share reservations.
o The client's re-use of an old, previously confirmed, shorthand
client identifier, a new callback value, and a new callback_ident
...
... o The client's re-use of an old, previously confirmed, shorthand
client identifier, a new callback value, and a new callback_ident
value. The client's use of SETCLIENTID_CONFIRM in this case MUST
...
... client identifier, a new callback value, and a new callback_ident
value. The client's use of SETCLIENTID_CONFIRM in this case MUST
NOT result in the removal of any previous leased state (locks,
...
...
We use the same notation and definitions for v, x, c, k, s, and
unconfirmed and confirmed client records as introduced in the
description of the SETCLIENTID operation. The arguments to
SETCLIENTID_CONFIRM are indicated by the notation { c, s }, where c
...
... returns the result cached in the DRC. The server does not remove
any relevant leased client state nor does it modify any recorded
callback and callback_ident information for client ...
... client state nor does it modify any recorded
callback and callback_ident information for client { x } as
represented by the shorthand value c.
...
... represented by the shorthand value c.
For a DRC miss, the server checks for client records that match the
shorthand value c. The processing cases are as follows:
...
... principals of the records do not match that of the
SETCLIENTID_CONFIRM, the server returns NFS4ERR_CLID_INUSE, and no
relevant leased client state is removed and no recorded callback
...
... state is removed and no recorded callback
and callback_ident information for client { x } is changed.
Otherwise, the confirmed { v, x, c, l, t } record is removed and
...
... the unconfirmed { v, x, c, k, s } is marked as confirmed, thereby
modifying recorded and confirmed callback and callback_ident
information for client { x }.
The server does not remove ...
... returns NFS4ERR_CLID_INUSE without removing any relevant leased
client state and without changing recorded callback and
callback_ident values for client ...
... client state and without changing recorded callback and
callback_ident values for client { x }.
If the principals ...
... If the principals match, then what has likely happened is that the
client never got the response from the SETCLIENTID_CONFIRM, and
the DRC entry has been purged. Whatever the scenario, since the
principals ...
... principals match, as well as { c, s } matching a confirmed record,
the server leaves client x's relevant leased client state intact,
...
... principals match, as well as { c, s } matching a confirmed record,
the server leaves client x's relevant leased client state intact,
leaves its callback and callback_ident values unmodified, and
...
... o The server has not recorded a confirmed { *, *, c, *, * }, and has
recorded an unconfirmed { *, x, c, k, s }. Even if this is a
retry from client, nonetheless the client's first
SETCLIENTID_CONFIRM attempt was not received by the server ...
... recorded an unconfirmed { *, x, c, k, s }. Even if this is a
retry from client, nonetheless the client's first
SETCLIENTID_CONFIRM attempt was not received by the server. Retry
...
... there is also a confirmed { *, x, d, *, t }, the server MUST
remove the client x's relevant leased client state, and overwrite
...
... *, s }. The server returns NFS4ERR_STALE_CLIENTID. The server
does not remove any relevant leased client state, nor does it
modify any recorded callback and callback_ident information for
...
... state, nor does it
modify any recorded callback and callback_ident information for
any client.
The server needs to cache ...
...
The server needs to cache unconfirmed { v, x, c, k, s } client
records and await for some time their confirmation. As should be
clear from the record processing discussions ...
... SETCLIENTID_CONFIRM, there are cases where the server does not
deterministically remove unconfirmed client records. To avoid
running out of resources, the server is not required to hold
unconfirmed records indefinitely. One strategy the server might use
...
... running out of resources, the server is not required to hold
unconfirmed records indefinitely. One strategy the server might use
is to set a limit on how many unconfirmed client records it will
maintain, and then when the limit would be exceeded, remove the
...
... of time is fairly arbitrary but it is surely no higher than the
server's lease time period. Consider that leases need to be renewed
before the lease time expires via an operation from the client. If
the client cannot issue a SETCLIENTID_CONFIRM after a SETCLIENTID
...
... before the lease time expires via an operation from the client. If
the client cannot issue a SETCLIENTID_CONFIRM after a SETCLIENTID
before a period of time equal to that of a lease expires, then the
client ...
... client cannot issue a SETCLIENTID_CONFIRM after a SETCLIENTID
before a period of time equal to that of a lease expires, then the
client is unlikely to be able maintain state on the server during
steady state ...
... state operation.
If the client does send a SETCLIENTID_CONFIRM for an unconfirmed
record that the server has already deleted, the client ...
... client does send a SETCLIENTID_CONFIRM for an unconfirmed
record that the server has already deleted, the client will get
NFS4ERR_STALE_CLIENTID back. If so, the client should then start ...
... deleted, the client will get
NFS4ERR_STALE_CLIENTID back. If so, the client should then start
over, and send SETCLIENTID to reestablish an unconfirmed client ...
... client should then start
over, and send SETCLIENTID to reestablish an unconfirmed client
record and get back an unconfirmed clientid and setclientid_confirm
verifier ...
... record and get back an unconfirmed clientid and setclientid_confirm
verifier. The client should then send the SETCLIENTID_CONFIRM to
confirm the clientid.
...
... SETCLIENTID_CONFIRM does not establish or renew a lease. However, if
SETCLIENTID_CONFIRM removes relevant leased client state, and that
state ...
... state does not include existing delegations, the server MUST allow
the client a period of time no less than the value of lease_time
attribute, to reclaim, (via the CLAIM_DELEGATE_PREV claim type of the
OPEN operation) its delegations ...
...
The VERIFY operation is used to verify that attributes have a value
assumed by the client before proceeding with following operations in
the compound request. If any of the attributes do not match then the
error NFS4ERR_NOT_SAME must be returned. The current filehandle
...
...
One possible use of the VERIFY operation is the following compound
sequence. With this the client is attempting to verify that the file
being removed will match what the client ...
... client is attempting to verify that the file
being removed will match what the client expects to be removed. This
sequence can help prevent the unintended deletion of a file.
...
... REMOVE (file name)
This sequence does not prevent a second client from removing and
creating a new file in the middle of this sequence but it does help
...
... operation and the server does not support that attribute for the
filesystem object, the error NFS4ERR_ATTRNOTSUPP is returned to the
client.
When the attribute rdattr_error or any write-only attribute (e.g.,
...
... When the attribute rdattr_error or any write-only attribute (e.g.,
time_modify_set) is specified, the error NFS4ERR_INVAL is returned to
the client.
ERRORS
...
... a count of 0 (zero) subject to permissions checking. The server may
choose to write fewer bytes than requested by the client.
Part of the write request is a specification of how the write is to
...
...
Part of the write request is a specification of how the write is to
be performed. The client specifies with the stable parameter the
method of how the data is to be processed by the server ...
... stable is 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 reply to the client. There is no guarantee whether
or when any uncommitted data will subsequently be committed to stable
storage. The only guarantees made by the server ...
... destroy any data without changing the value of verf and that it will
not commit the data and metadata at a level less than that requested
by the client.
The stateid value for a WRITE request represents a value returned
...
... valid and to update lease
timeouts for the client.
Upon successful completion, the following results are returned. The
...
... verifier is a cookie that the client can use to determine whether the
server has changed instance (boot) state between a call to WRITE and
...
... protocol server, where uncommitted data may be lost.
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, the client ...
... 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, 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 possible that due to client crash or other error that a subsequent
...
... metadata with the server's stable storage, barring client error. It
is possible that due to client crash or other error that a subsequent
COMMIT will not be received by the server.
...
...
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
an error unless no data was written at all. If the server writes
...
... an error unless no data was written at all. If the server writes
less than the number of bytes specified, the client should issue
another WRITE to write the remaining data.
...
... uncommitted data may be lost. In the most likely case, the verifier
allows the client to detect server reboots. This information is
required so that the client can safely determine whether the server
...
... allows the client to detect server reboots. This information is
required so that the client can safely determine whether the server
could have lost cached data. If the server fails unexpectedly and
the client ...
... client can safely determine whether the server
could have lost cached data. If the server fails unexpectedly and
the client has uncommitted data from previous WRITE requests (done
with the stable argument set to UNSTABLE4 and in which the result
committed was returned as UNSTABLE4 as well) it may not have flushed
...
... committed was returned as UNSTABLE4 as well) it may not have flushed
cached data to stable storage. The burden of recovery is on the
client and the client will need to retransmit the data to the server.
...
... cached data to stable storage. The burden of recovery is on the
client and the client will need to retransmit the data to the server.
A suggested verifier ...
... buffers).
The committed field in the results allows the client to do more
effective caching. If the server is committing all WRITE requests to
stable storage, then it should return with committed set to
...
... FILE_SYNC4, regardless of the value of the stable field in the
arguments. A server that uses an NVRAM accelerator may choose to
implement this policy. The client can use this to increase the
effectiveness of the cache by discarding cached data that has already
...
... record of the data to be written file is read or write locked by an
owner that is not associated with the stateid, the server will return
NFS4ERR_LOCKED. If so, the client must check if the owner
corresponding to the stateid used with the WRITE operation has a
conflicting read lock that overlaps with the region that was to be
...
... conflicting read lock that overlaps with the region that was to be
written. If the stateid's owner has no conflicting read lock, then
the client should try to get the appropriate write record lock via
the LOCK operation before re-attempting the WRITE. When the WRITE
completes, the client ...
... client should try to get the appropriate write record lock via
the LOCK operation before re-attempting the WRITE. When the WRITE
completes, the client should release the record lock via LOCKU.
If the stateid's owner had a conflicting read lock, then the client ...
... client should release the record lock via LOCKU.
If the stateid's owner had a conflicting read lock, then the client
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
...
... upgrade this read lock to a write lock, or the server has no upgrade
capability. If the server attempted to upgrade the read lock and
failed, it is pointless for the client to re-attempt the upgrade via
the LOCK operation, because there might be another client also trying
...
... failed, it is pointless for the client to re-attempt the upgrade via
the LOCK operation, because there might be another client also trying
to upgrade. If two clients are blocked trying upgrade the same lock,
...
... the LOCK operation, because there might be another client also trying
to upgrade. If two clients are blocked trying upgrade the same lock,
the clients deadlock. If the server has no upgrade capability, then
...
... to upgrade. If two clients are blocked trying upgrade the same lock,
the clients deadlock. If the server has no upgrade capability, then
it is pointless to try a LOCK operation to upgrade.
...
...
This operation is used to notify the server that the lock_owner is no
longer in use by the client. This allows the server to release
cached state related to the specified lock_owner. If file locks,
...
... IMPLEMENTATION
The client may choose to use this operation to ease the amount of
server state that is held. Depending on behavior of applications at
...
... server state that is held. Depending on behavior of applications at
the client, it may be important for the client to use this operation
since the server has certain obligations with respect to holding a
...
... server state that is held. Depending on behavior of applications at
the client, it may be important for the client to use this operation
since the server has certain obligations with respect to holding a
reference to a lock_owner as long as the associated file is open.
...
... since the server has certain obligations with respect to holding a
reference to a lock_owner as long as the associated file is open.
Therefore, if the client knows for certain that the lock_owner will
no longer be used under the context of the associated open_owner4, it
...
... This operation is a placeholder for encoding a result to handle the
case of the client sending an operation code within COMPOUND that is
not supported. See the COMPOUND procedure description for more
details.
...
... IMPLEMENTATION
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
any other invalid operation code. Note that if the server gets an
...
...
The procedures used for callbacks are defined in the following
sections. In the interest of clarity, the terms "client" and
"server" refer to NFS clients and servers ...
... client" and
"server" refer to NFS clients and servers, despite the fact that for
an individual callback RPC, the sense of these terms would be
...
... there is no direct functionality associated with this procedure, the
server will use CB_NULL to confirm the existence of a path for RPCs
from server to client.
ERRORS
...
... wrapper.
In 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 the operations within the CB_COMPOUND sequence. In this case, the
...
... COMPOUND - Compound Operations".
The value of callback_ident is supplied by the client during
SETCLIENTID. The server must use the client supplied callback_ident
...
... The value of callback_ident is supplied by the client during
SETCLIENTID. The server must use the client supplied callback_ident
during the CB_COMPOUND to allow the client to properly identify the
...
... SETCLIENTID. The server must use the client supplied callback_ident
during the CB_COMPOUND to allow the client to properly identify the
server.
...
... The CB_COMPOUND procedure is used to combine individual operations
into a single RPC request. The client interprets each of the
operations in turn. If an operation is executed by the client and
...
... RPC request. The client interprets each of the
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 CB_COMPOUND procedure is executed. The client ...
... by the client and
the status of that operation is NFS4_OK, then the next operation in
the CB_COMPOUND procedure is executed. The client continues this
process until there are no more operations to be executed or one of
the operations has a status value other than NFS4_OK.
...
... state of a file that has been write delegated.
The attributes size and change are the only ones guaranteed to be
serviced by the client. See the section "Handling of CB_GETATTR"
for a full description of how the client and server are to interact
...
... serviced by the client. See the section "Handling of CB_GETATTR"
for a full description of how the client and server are to interact
with the use of CB_GETATTR.
...
... with the use of CB_GETATTR.
If the filehandle specified is not one for which the client holds a
write open delegation, an NFS4ERR_BADHANDLE error is returned.
...
... IMPLEMENTATION
The client returns attrmask bits and the associated attribute
values only for the change attribute, and attributes that it may
...
...
The truncate flag is used to optimize recall for a file which is
about to be truncated to zero. When it is set, the client is freed
of obligation to propagate modified data for the file to the server,
since this data is irrelevant.
...
... since this data is irrelevant.
If the handle specified is not one for which the client holds an open
delegation, an NFS4ERR_BADHANDLE error is returned.
...
... IMPLEMENTATION
The client should reply to the callback immediately. Replying does
not complete the recall except when an error was returned. The
recall is not complete until the delegation ...
... This operation is a placeholder for encoding a result to handle the
case of the client sending an operation code within COMPOUND that is
not supported. See the COMPOUND procedure description for more
details.
...
... A server will probably not send an operation with code OP_CB_ILLEGAL
but if it does, the response will be CB_ILLEGAL4res just as it would
be with any other invalid operation code. Note that if the client
gets an illegal operation code that is not OP_ILLEGAL, and if the
...
...
gets an illegal operation code that is not OP_ILLEGAL, and if the
client checks for legal operation codes during the XDR decode phase,
then the CB_ILLEGAL4res would not be returned.
...
... NFS has historically used a model where, from an authentication
perspective, the client was the entire machine, or at least the
source IP address of the machine. The NFS ...
... NFS server relied on the NFS
client to make the proper authentication of the end-user. The NFS ...
... end-user. The NFS
server in turn shared its files only to specific clients, as
identified by the client's source IP address ...
... server in turn shared its files only to specific clients, as
identified by the client's source IP address. Given this model, the
AUTH ...
... security flavor simply identified the end-user using the
client to the NFS server. When processing NFS responses, the client ...
... client to the NFS server. When processing NFS responses, the client
ensured that the responses came from the same IP address and port
number ...
... authentication, where an end-user on a
client mutually authenticates (via cryptographic schemes that do not
...
... an attacker in between the NFS client and server that modifies the
RPC request and/or the response. While implementations are free to
...
...
The first such operation is SECINFO. It is recommended that the
client issue the SECINFO call such that it is protected with a
security flavor that has integrity protection ...
... SECINFO and therefore its results, an attacker in the middle could
modify results such that the client might select a weaker algorithm
in the set allowed by server, making the client and/or server ...
... client might select a weaker algorithm
in the set allowed by server, making the client and/or server
vulnerable to further attacks.
...
... steps. First the attacker modifies the unprotected results of some
operation to return NFS4ERR_MOVED. Second, when the client follows up
with a GETATTR for the fs_locations attribute, the attacker modifies
...
... with a GETATTR for the fs_locations attribute, the attacker modifies
the results to cause the client migrate its traffic to a server
controlled by the attacker ...
...
Because the operations SETCLIENTID/SETCLIENTID_CONFIRM are
responsible for the release of client state, it is imperative that
the principal ...
... the principal used for these operations is checked against and match
the previous use of these operations. See the section "Client ID"
for further discussion.
...
... syntax and semantics of these
fields to effectively communicate callback information between client
and server. Therefore, an IANA registry has been created to include
...
...
/*
* Change info for the client
*/
struct change_info4 {
...
...
/*
* Callback program info as provided by the client
*/
struct cb_client4 {
...
... /* Right to file based on a delegation granted to a previous boot
* instance of the client. File is specified by name.
*/
case CLAIM_DELEGATE_PREV:
...
... (CLAIM_PREVIOUS) */
nfs_space_limit4 space_limit; /* Defines condition that
the client must check to
determine whether the
file needs to be flushed
...
... * Result flags
*/
/* Client must confirm open */
const OPEN4_RESULT_CONFIRM = 0x00000002;
/* Type of file locking behavior at the server */
...
... SETCLIENTID4resok resok4;
case NFS4ERR_CLID_INUSE:
clientaddr4 client_using;
default:
void;
...
... /*
* Program number is in the transient range since the client
* will assign the exact transient program number and provide
* that to the server via the SETCLIENTID operation.
...