If the client does not request the attribute, the server has no
choice but to return failure for the entire READDIR operation.
For some file system environments, the directory entries "." and
".." 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 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 directory presentation to the application.
For READDIR arguments, cookie values of 1 and 2 should not be used
and for READDIR results cookie values of 0, 1, and 2 should not
returned.
On success, the current filehandle retains its value.
IMPLEMENTATION
The server's file system 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 during a READDIR, the server has an
idea of how to limit the encoded response. The dircount field
provides a hint on the number of entries based solely on the names
of the directory entries. Since it is a hint, it may be possible
that a dircount value is zero. In this case, the server is free
to ignore the dircount value and return directory information
based on the specified maxcount value.
The cookieverf may be used by the server to help manage cookie
values that may become stale. It should be a rare occurrence that
a server is unable to continue properly reading a directory with
the provided 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.
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 has been migrated, the server may or may not be able to use
the same 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 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.
Since some servers will not be returning "." and ".." entries as
has been done with previous versions of the NFS protocol, the
client that requires these entries be present in READDIR responses
must fabricate them.
ERRORS
NFS4ERR_ACCES
NFS4ERR_BADHANDLE
NFS4ERR_BAD_COOKIE
NFS4ERR_DELAY
NFS4ERR_FHEXPIRED
NFS4ERR_INVAL
NFS4ERR_IO
NFS4ERR_MOVED
NFS4ERR_NOFILEHANDLE
NFS4ERR_NOTDIR
NFS4ERR_NOTSUPP
NFS4ERR_READDIR_NOSPC
NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT
NFS4ERR_STALE
NFS4ERR_TOOSMALL
NFS4ERR_WRONGSEC
14.2.25. Operation 27: READLINK - Read Symbolic Link
SYNOPSIS
(cfh) -> linktext
ARGUMENT
/* CURRENT_FH: symlink */
void;
RESULT
struct READLINK4resok {
linktext4 link;
};
union READLINK4res switch (nfsstat4 status) {
case NFS4_OK:
READLINK4resok resok4;
default:
void;
};
DESCRIPTION
READLINK reads the data associated with a symbolic link. The data
is a UTF-8 string that is opaque to the server. That is, whether
created by an NFS client or created locally on the server, the
data in a symbolic link is not interpreted when created, but is
simply stored.
On success, the current filehandle retains its value.
IMPLEMENTATION
A symbolic link is nominally a pointer to another file. The data
is 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. A READLINK operation returns the data to the
client for interpretation. If different implementations want to
share access to symbolic links, then they must agree on the
interpretation of the data in the symbolic link.
The READLINK operation is only allowed on objects of type NF4LNK.
The server should return the error, NFS4ERR_INVAL, if the object
is not of type, NF4LNK.
ERRORS
NFS4ERR_ACCES
NFS4ERR_BADHANDLE
NFS4ERR_DELAY
NFS4ERR_FHEXPIRED
NFS4ERR_INVAL
NFS4ERR_IO
NFS4ERR_MOVED
NFS4ERR_NOFILEHANDLE
NFS4ERR_NOTSUPP
NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT
NFS4ERR_STALE
NFS4ERR_WRONGSEC
14.2.26. Operation 28: REMOVE - Remove Filesystem Object
SYNOPSIS
(cfh), filename -> change_info
ARGUMENT
struct REMOVE4args {
/* CURRENT_FH: directory */
component4 target;
};
RESULT
struct REMOVE4resok {
change_info4 cinfo;
}
union REMOVE4res switch (nfsstat4 status) {
case NFS4_OK:
REMOVE4resok resok4;
default:
void;
}
DESCRIPTION
The REMOVE operation removes (deletes) a directory entry named by
filename from the directory corresponding to the current
filehandle. If the entry in the directory was the last reference
to the corresponding file system object, the object may be
destroyed.
For the directory where the filename was removed, the server
returns change_info4 information in cinfo. With the atomic field
of the change_info4 struct, the server will indicate if the before
and after change attributes were obtained atomically with respect
to the removal.
If the target has a length of 0 (zero), or if target does not obey
the UTF-8 definition, the error NFS4ERR_INVAL will be returned.
On success, the current filehandle retains its value.
IMPLEMENTATION
NFS versions 2 and 3 required a different operator RMDIR for
directory removal. NFS version 4 REMOVE can be used to delete any
directory entry independent of its file type.
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 file handle. 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 needs to be able to continue to access a file after
using 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.
ERRORS
NFS4ERR_ACCES
NFS4ERR_BADHANDLE
NFS4ERR_DELAY
NFS4ERR_FHEXPIRED
NFS4ERR_IO
NFS4ERR_MOVED
NFS4ERR_NAMETOOLONG
NFS4ERR_NOENT
NFS4ERR_NOFILEHANDLE
NFS4ERR_NOTDIR
NFS4ERR_NOTEMPTY
NFS4ERR_NOTSUPP
NFS4ERR_RESOURCE
NFS4ERR_ROFS
NFS4ERR_SERVERFAULT
NFS4ERR_STALE
NFS4ERR_WRONGSEC
14.2.27. Operation 29: RENAME - Rename Directory Entry
SYNOPSIS
(sfh), oldname (cfh), newname -> source_change_info,
target_change_info
ARGUMENT
struct RENAME4args {
/* SAVED_FH: source directory */
component4 oldname;
/* CURRENT_FH: target directory */
component4 newname;
};
RESULT
struct RENAME4resok {
change_info4 source_cinfo;
change_info4 target_cinfo;
};
union RENAME4res switch (nfsstat4 status) {
case NFS4_OK:
RENAME4resok resok4;
default:
void;
};
DESCRIPTION
The RENAME operation renames the object identified by oldname in
the source directory corresponding to the saved filehandle, as set
by the SAVEFH operation, to newname in the 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 file system on the server. On
success, the current filehandle will continue to be the target
directory.
If the target directory already contains an entry with the name,
newname, the source object must be compatible with the target:
either both are non-directories or both are directories and the
target must be empty. If compatible, the existing target is
removed before the rename occurs. If they are not compatible or
if the target is a directory but not empty, the server will return
the error, NFS4ERR_EXIST.
If oldname and newname both refer to the same file (they might be
hard links of each other), then RENAME should perform no action
and return success.
For both directories involved in the RENAME, the server returns
change_info4 information. With the atomic field of the
change_info4 struct, the server will indicate if the before and
after change attributes were obtained atomically with respect to
the rename.
If the oldname or newname has a length of 0 (zero), or if oldname
or newname does not obey the UTF-8 definition, the error
NFS4ERR_INVAL will be returned.
IMPLEMENTATION
The RENAME operation must be atomic to the client. The statement
"source and target directories must reside on the same file system
on the server" means that the fsid fields in the attributes for
the directories are the same. If they reside on different file
systems, the error, NFS4ERR_XDEV, is returned.
A filehandle may or may not become stale or expire on a rename.
However, server implementors are strongly encouraged to attempt to
keep file handles from becoming stale or expiring in this fashion.
On some servers, the filenames, "." and "..", are illegal as
either oldname or newname. In addition, neither oldname nor
newname can be an alias for the source directory. These servers
will return the error, NFS4ERR_INVAL, in these cases.
ERRORS
NFS4ERR_ACCES
NFS4ERR_BADHANDLE
NFS4ERR_DELAY
NFS4ERR_DQUOT
NFS4ERR_EXIST
NFS4ERR_FHEXPIRED
NFS4ERR_INVAL
NFS4ERR_IO
NFS4ERR_ISDIR
NFS4ERR_MOVED
NFS4ERR_NAMETOOLONG
NFS4ERR_NOENT
NFS4ERR_NOFILEHANDLE
NFS4ERR_NOSPC
NFS4ERR_NOTDIR
NFS4ERR_NOTEMPTY
NFS4ERR_NOTSUPP
NFS4ERR_RESOURCE
NFS4ERR_ROFS
NFS4ERR_SERVERFAULT
NFS4ERR_STALE
NFS4ERR_WRONGSEC
NFS4ERR_XDEV
14.2.28. Operation 30: RENEW - Renew a Lease
SYNOPSIS
stateid -> ()
ARGUMENT
struct RENEW4args {
stateid4 stateid;
};
RESULT
struct RENEW4res {
nfsstat4 status;
};
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
server renews all leases associated with the client. The
associated leases are determined by the client id provided via the
SETCLIENTID procedure.
The stateid for RENEW may not be one of the special stateids
consisting of all bits 0 (zero) or all bits 1.
IMPLEMENTATION
ERRORS
NFS4ERR_BAD_STATEID
NFS4ERR_EXPIRED
NFS4ERR_GRACE
NFS4ERR_INVAL
NFS4ERR_LEASE_MOVED
NFS4ERR_MOVED
NFS4ERR_OLD_STATEID
NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT
NFS4ERR_STALE_STATEID
NFS4ERR_WRONGSEC
14.2.29. Operation 31: RESTOREFH - Restore Saved Filehandle
SYNOPSIS
(sfh) -> (cfh)
ARGUMENT
/* SAVED_FH: */
void;
RESULT
struct RESTOREFH4res {
/* CURRENT_FH: value of saved fh */
nfsstat4 status;
};
DESCRIPTION
Set the current filehandle to the value in the saved filehandle.
If there is no saved filehandle then return an error
NFS4ERR_NOFILEHANDLE.
IMPLEMENTATION
Operations like OPEN and LOOKUP use the current filehandle to
represent a directory and replace it with a new filehandle.
Assuming the previous filehandle was saved with a SAVEFH operator,
the previous filehandle can be restored as the current filehandle.
This is commonly used to obtain post-operation attributes for the
directory, e.g.
PUTFH (directory filehandle)
SAVEFH
GETATTR attrbits (pre-op dir attrs)
CREATE optbits "foo" attrs
GETATTR attrbits (file attributes)
RESTOREFH
GETATTR attrbits (post-op dir attrs)
ERRORS
NFS4ERR_BADHANDLE
NFS4ERR_FHEXPIRED
NFS4ERR_MOVED
NFS4ERR_NOFILEHANDLE
NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT
NFS4ERR_STALE
NFS4ERR_WRONGSEC
14.2.30. Operation 32: SAVEFH - Save Current Filehandle
SYNOPSIS
(cfh) -> (sfh)
ARGUMENT
/* CURRENT_FH: */
void;
RESULT
struct SAVEFH4res {
/* SAVED_FH: value of current fh */
nfsstat4 status;
};
DESCRIPTION
Save the current filehandle. If a previous filehandle was saved
then it is no longer accessible. The saved filehandle can be
restored as the current filehandle with the RESTOREFH operator.
On success, the current filehandle retains its value.
IMPLEMENTATION
ERRORS
NFS4ERR_BADHANDLE
NFS4ERR_FHEXPIRED
NFS4ERR_MOVED
NFS4ERR_NOFILEHANDLE
NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT
NFS4ERR_STALE
NFS4ERR_WRONGSEC
14.2.31. Operation 33: SECINFO - Obtain Available Security
SYNOPSIS
(cfh), name -> { secinfo }
ARGUMENT
struct SECINFO4args {
/* CURRENT_FH: */
component4 name;
};
RESULT
enum rpc_gss_svc_t {
RPC_GSS_SVC_NONE = 1,
RPC_GSS_SVC_INTEGRITY = 2,
RPC_GSS_SVC_PRIVACY = 3
};
struct rpcsec_gss_info {
sec_oid4 oid;
qop4 qop;
rpc_gss_svc_t service;
};
struct secinfo4 {
uint32_t flavor;
opaque flavor_info<>; /* null for AUTH_SYS, AUTH_NONE;
contains rpcsec_gss_info for
RPCSEC_GSS. */
};
typedef secinfo4 SECINFO4resok<>;
union SECINFO4res switch (nfsstat4 status) {
case NFS4_OK:
SECINFO4resok resok4;
default:
void;
};
DESCRIPTION
The SECINFO operation is used by the client to obtain a list of
valid RPC authentication flavors for a specific file handle, file
name pair. The result will contain an array which represents the
security mechanisms available. The array entries are represented
by the secinfo4 structure. The field 'flavor' will contain a
value of AUTH_NONE, AUTH_SYS (as defined in [RFC1831]), or
RPCSEC_GSS (as defined in [RFC2203]).
For the flavors, AUTH_NONE, and AUTH_SYS no additional security
information is returned. For a return value of RPCSEC_GSS, a
security triple is returned that contains the mechanism object id
(as defined in [RFC2078]), the quality of protection (as defined
in [RFC2078]) and the service type (as defined in [RFC2203]). It
is possible for SECINFO to return multiple entries with flavor
equal to RPCSEC_GSS with different security triple values.
On success, the current filehandle retains its value.
IMPLEMENTATION
The SECINFO operation is expected to be used by the NFS client
when the 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 point, the client is expected to obtain a list of
possible security flavors and choose what best suits its policies.
It is recommended that the client issue the SECINFO call protected
by a security triple that uses either rpc_gss_svc_integrity or
rpc_gss_svc_privacy service. The use of rpc_gss_svc_none would
allow an attacker in the middle to modify the SECINFO results such
that the client might select a weaker algorithm in the set allowed
by server, making the client and/or server vulnerable to further
attacks.
ERRORS
NFS4ERR_BADHANDLE
NFS4ERR_FHEXPIRED
NFS4ERR_MOVED
NFS4ERR_NAMETOOLONG
NFS4ERR_NOENT
NFS4ERR_NOFILEHANDLE
NFS4ERR_NOTDIR
NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT
NFS4ERR_STALE
NFS4ERR_WRONGSEC
14.2.32. Operation 34: SETATTR - Set Attributes
SYNOPSIS
(cfh), attrbits, attrvals -> -
ARGUMENT
struct SETATTR4args {
/* CURRENT_FH: target object */
stateid4 stateid;
fattr4 obj_attributes;
};
RESULT
struct SETATTR4res {
nfsstat4 status;
bitmap4 attrsset;
};
DESCRIPTION
The SETATTR operation changes one or more of the attributes of a
file system object. The new attributes are specified with a
bitmap and the attributes that follow the bitmap in bit order.
The stateid is necessary for SETATTRs that change the size of a
file (modify the attribute object_size). This stateid represents
a record lock, share reservation, or delegation which must be
valid for the SETATTR to modify the file data. A valid stateid
would always be specified. When the file size is not changed, the
special stateid consisting of all bits 0 (zero) should be used.
On either success or failure of the operation, the server will
return the attrsset bitmask to represent what (if any) attributes
were successfully set.
On success, the current filehandle retains its value.
IMPLEMENTATION
The file size attribute is used to request changes to the size of
a file. A value of 0 (zero) causes the file to be truncated, a
value less than the current size of the file causes data from new
size to the end of the file to be discarded, and a size greater
than the 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 extending the file size via
SETATTR.
SETATTR is not guaranteed atomic. A failed SETATTR may partially
change a file's attributes.
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.
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 time skew.
If the server cannot successfully set all the attributes it must
return an NFS4ERR_INVAL error. If the server can only support 32
bit offsets and sizes, a SETATTR request to set the size of a file
to larger than can be represented in 32 bits will be rejected with
this same error.
ERRORS
NFS4ERR_ACCES
NFS4ERR_BADHANDLE
NFS4ERR_BAD_STATEID
NFS4ERR_DELAY
NFS4ERR_DENIED
NFS4ERR_DQUOT
NFS4ERR_EXPIRED
NFS4ERR_FBIG
NFS4ERR_FHEXPIRED
NFS4ERR_GRACE
NFS4ERR_INVAL
NFS4ERR_IO
NFS4ERR_MOVED
NFS4ERR_NOFILEHANDLE
NFS4ERR_NOSPC
NFS4ERR_NOTSUPP
NFS4ERR_OLD_STATEID
NFS4ERR_PERM
NFS4ERR_RESOURCE
NFS4ERR_ROFS
NFS4ERR_SERVERFAULT
NFS4ERR_STALE
NFS4ERR_STALE_STATEID
NFS4ERR_WRONGSEC
14.2.33. Operation 35: SETCLIENTID - Negotiate Clientid
SYNOPSIS
client, callback -> clientid, setclientid_confirm
ARGUMENT
struct SETCLIENTID4args {
nfs_client_id4 client;
cb_client4 callback;
};
RESULT
struct SETCLIENTID4resok {
clientid4 clientid;
verifier4 setclientid_confirm;
};
union SETCLIENTID4res switch (nfsstat4 status) {
case NFS4_OK:
SETCLIENTID4resok resok4;
case NFS4ERR_CLID_INUSE:
clientaddr4 client_using;
default:
void;
};
DESCRIPTION
The SETCLIENTID operation introduces the ability of the client to
notify the server of its intention to use a particular client
identifier and verifier pair. Upon successful completion the
server will return a clientid which is used in subsequent file
locking requests and a confirmation verifier. The client will use
the SETCLIENTID_CONFIRM operation to return the verifier to the
server. At that point, the client may use the clientid in
subsequent operations that require an nfs_lockowner.
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 must correctly reflect the program and port
numbers for the callback program at the time SETCLIENTID is used.
IMPLEMENTATION
The server takes the verifier and client identification supplied
in the nfs_client_id4 and searches for a match of the client
identification. If no match is found the server saves the
principal/uid information along with the verifier and client
identification and returns a unique clientid that is used as a
shorthand reference to the supplied information.
If the server finds matching client identification and a
corresponding match in principal/uid, the server releases all
locking state for the client and returns a new clientid.
The principal, or principal to user-identifier mapping is taken
from the credential presented in the RPC. As mentioned, the
server will use the credential and associated principal for the
matching with existing clientids. If the client is a traditional
host-based client like a Unix NFS client, then the credential
presented may be the host credential. If the client is a user
level client or lightweight client, the credential used may be the
end user's credential. The client should take care in choosing an
appropriate credential since denial of service attacks could be
attempted by a rogue client that has access to the credential.
ERRORS
NFS4ERR_CLID_INUSE
NFS4ERR_INVAL
NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT
14.2.34. Operation 36: SETCLIENTID_CONFIRM - Confirm Clientid
SYNOPSIS
setclientid_confirm -> -
ARGUMENT
struct SETCLIENTID_CONFIRM4args {
verifier4 setclientid_confirm;
};
RESULT
struct SETCLIENTID_CONFIRM4res {
nfsstat4 status;
};
DESCRIPTION
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) opaque confirmation
verifier. The server responds with a simple status of success or
failure.
IMPLEMENTATION
The client must use the SETCLIENTID_CONFIRM operation to confirm
its use of client identifier. If the server is holding state for
a client which has presented a new verifier via SETCLIENTID, then
the state will not be released, as described in the section
"Client Failure and Recovery", until a valid SETCLIENTID_CONFIRM
is received. Upon successful confirmation the server will release
the previous state held on behalf of the client. The server
should choose a confirmation cookie value that is reasonably
unique for the client.
ERRORS
NFS4ERR_CLID_INUSE
NFS4ERR_INVAL
NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT
NFS4ERR_STALE_CLIENTID
14.2.35. Operation 37: VERIFY - Verify Same Attributes
SYNOPSIS
(cfh), fattr -> -
ARGUMENT
struct VERIFY4args {
/* CURRENT_FH: object */
fattr4 obj_attributes;
};
RESULT
struct VERIFY4res {
nfsstat4 status;
};
DESCRIPTION
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 retains its value after successful completion
of the operation.
IMPLEMENTATION
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 expects to be
removed. This sequence can help prevent the unintended deletion
of a file.
PUTFH (directory filehandle)
LOOKUP (file name)
VERIFY (filehandle == fh)
PUTFH (directory filehandle)
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 avoid the unintended result.
In the case that a recommended attribute is specified in the
VERIFY operation and the server does not support that attribute
for the file system object, the error NFS4ERR_NOTSUPP is returned
to the client.
ERRORS
NFS4ERR_ACCES
NFS4ERR_BADHANDLE
NFS4ERR_DELAY
NFS4ERR_FHEXPIRED
NFS4ERR_INVAL
NFS4ERR_MOVED
NFS4ERR_NOFILEHANDLE
NFS4ERR_NOTSUPP
NFS4ERR_NOT_SAME
NFS4ERR_RESOURCE
NFS4ERR_SERVERFAULT
NFS4ERR_STALE
NFS4ERR_WRONGSEC
14.2.36. Operation 38: WRITE - Write to File
SYNOPSIS
(cfh), offset, count, stability, stateid, data -> count, committed,
verifier
ARGUMENT
enum stable_how4 {
UNSTABLE4 = 0,
DATA_SYNC4 = 1,
FILE_SYNC4 = 2
};
struct WRITE4args {
/* CURRENT_FH: file */
stateid4 stateid;
offset4 offset;
stable_how4 stable;
opaque data<>;
};
RESULT
struct WRITE4resok {
count4 count;
stable_how4 committed;
verifier4 writeverf;
};
union WRITE4res switch (nfsstat4 status) {
case NFS4_OK:
WRITE4resok resok4;
default:
void;
};
DESCRIPTION
The WRITE operation is used to write data to a regular file. The
target file is specified by the current filehandle. The offset
specifies the offset where the data should be written. An offset
of 0 (zero) specifies that the write should start at the beginning
of the file. The count represents the number of bytes of data
that are to be written. If the count is 0 (zero), the WRITE will
succeed and return 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 be performed. The client specifies with the stable parameter
the method of how the data is to be processed by the server. If
stable is FILE_SYNC4, the server must commit the data written plus
all file system metadata to stable storage before returning
results. This corresponds to the NFS version 2 protocol
semantics. Any other behavior constitutes a protocol violation.
If stable is DATA_SYNC4, then the server must commit all of the
data to stable storage and enough of the metadata to retrieve the
data before returning. The server implementor is free to
implement DATA_SYNC4 in the same fashion as FILE_SYNC4, but with a
possible performance drop. If stable is UNSTABLE4, the server is
free to commit any part of the data and the 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 are that it will not 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 returned from a previous record lock or share
reservation request is provided as part of the argument. The
stateid is used by the server to verify that the associated lock
is still valid and to update lease timeouts for the client.
Upon successful completion, the following results are returned.
The count result is the number of bytes of data written to the
file. The server may write fewer bytes than requested. If so, the
actual number of bytes written starting at location, offset, is
returned.
The server also returns an indication of the level of commitment
of the data and metadata via committed. If the server committed
all data and metadata to stable storage, committed should be set
to FILE_SYNC4. If the level of commitment was at least as strong
as DATA_SYNC4, then committed should be set to DATA_SYNC4.
Otherwise, committed must be returned as UNSTABLE4. If stable was
FILE4_SYNC, then committed must also be FILE_SYNC4: anything else
constitutes a protocol violation. If stable was DATA_SYNC4, then
committed may be FILE_SYNC4 or DATA_SYNC4: anything else
constitutes a protocol violation. If stable was UNSTABLE4, then
committed may be either FILE_SYNC4, DATA_SYNC4, or UNSTABLE4.
The final portion of the result is the write verifier, verf. The
write verifier is a cookie that the client can use to determine
whether the server has changed state between a call to WRITE and a
subsequent call to either WRITE or COMMIT. This cookie must be
consistent during a single instance of the NFS version 4 protocol
service and must be unique between instances of the NFS version 4
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 will follow up some time in
the future with a 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 COMMIT will not be received by the
server.
On success, the current filehandle retains its value.
IMPLEMENTATION
It is possible for the server to write fewer than count bytes of
data. In this case, the server should not return an error unless
no data was written at all. If the server writes less than count
bytes, the client should issue another WRITE to write the
remaining data.
It is assumed that the act of writing data to a file will cause
the time_modified of the file to be updated. However, the
time_modified of the file should not be changed unless the
contents of the file are changed. Thus, a WRITE request with
count set to 0 should not cause the time_modified of the file to
be updated.
The definition of stable storage has been historically a point of
contention. The following expected properties of stable storage
may help in resolving design issues in the implementation. Stable
storage is persistent storage that survives:
1. Repeated power failures.
2. Hardware failures (of any board, power supply, etc.).
3. Repeated software crashes, including reboot cycle.
This definition does not address failure of the stable storage
module itself.
The verifier is defined to allow a client to detect different
instances of an NFS version 4 protocol server over which cached,
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 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 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 would be to use the time that the server was
booted or the time the server was last started (if restarting the
server without a reboot results in lost 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 been committed on the server.
Some implementations may return NFS4ERR_NOSPC instead of
NFS4ERR_DQUOT when a user's quota is exceeded.
ERRORS
NFS4ERR_ACCES
NFS4ERR_BADHANDLE
NFS4ERR_BAD_STATEID
NFS4ERR_DELAY
NFS4ERR_DENIED
NFS4ERR_DQUOT
NFS4ERR_EXPIRED
NFS4ERR_FBIG
NFS4ERR_FHEXPIRED
NFS4ERR_GRACE
NFS4ERR_INVAL
NFS4ERR_IO
NFS4ERR_LEASE_MOVED
NFS4ERR_LOCKED
NFS4ERR_MOVED
NFS4ERR_NOFILEHANDLE
NFS4ERR_NOSPC
NFS4ERR_OLD_STATEID
NFS4ERR_RESOURCE
NFS4ERR_ROFS
NFS4ERR_SERVERFAULT
NFS4ERR_STALE
NFS4ERR_STALE_STATEID
NFS4ERR_WRONGSEC
15. NFS Version 4 Callback Procedures
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, despite the fact that for
an individual callback RPC, the sense of these terms would be
precisely the opposite.
15.1. Procedure 0: CB_NULL - No Operation
SYNOPSIS
<null>
ARGUMENT
void;
RESULT
void;
DESCRIPTION
Standard NULL procedure. Void argument, void response. Even
though 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
None.
15.2. Procedure 1: CB_COMPOUND - Compound Operations
SYNOPSIS
compoundargs -> compoundres
ARGUMENT
enum nfs_cb_opnum4 {
OP_CB_GETATTR = 3,
OP_CB_RECALL = 4 };
union nfs_cb_argop4 switch (unsigned argop) {
case OP_CB_GETATTR: CB_GETATTR4args opcbgetattr;
case OP_CB_RECALL: CB_RECALL4args opcbrecall; };
struct CB_COMPOUND4args {
utf8string tag;
uint32_t minorversion;
nfs_cb_argop4 argarray<>; };
RESULT
union nfs_cb_resop4 switch (unsigned resop){
case OP_CB_GETATTR: CB_GETATTR4res opcbgetattr;
case OP_CB_RECALL: CB_RECALL4res opcbrecall; };
struct CB_COMPOUND4res {
nfsstat4 status;
utf8string tag;
nfs_cb_resop4 resarray<>; };
DESCRIPTION
The CB_COMPOUND procedure is used to combine one or more of the
callback procedures into a single RPC request. The main callback
RPC program has two main procedures: CB_NULL and CB_COMPOUND. All
other operations use the CB_COMPOUND procedure as a 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 error NFS4ERR_RESOURCE will be returned for the
particular operation within the CB_COMPOUND procedure where the
resource exhaustion occurred. This assumes that all previous
operations within the CB_COMPOUND sequence have been evaluated
successfully.
Contained within the CB_COMPOUND results is a 'status' field.
This status must be equivalent to the status of the last operation
that was executed within the CB_COMPOUND procedure. Therefore, if
an operation incurred an error then the 'status' value will be the
same error value as is being returned for the operation that
failed.
IMPLEMENTATION
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
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.
ERRORS
NFS4ERR_BADHANDLE
NFS4ERR_BAD_STATEID
NFS4ERR_RESOURCE
15.2.1. Operation 3: CB_GETATTR - Get Attributes
SYNOPSIS
fh, attrbits -> attrbits, attrvals
ARGUMENT
struct CB_GETATTR4args {
nfs_fh4 fh;
bitmap4 attr_request;
};
RESULT
struct CB_GETATTR4resok {
fattr4 obj_attributes;
};
union CB_GETATTR4res switch (nfsstat4 status) {
case NFS4_OK:
CB_GETATTR4resok resok4;
default:
void;
};
DESCRIPTION
The CB_GETATTR operation is used to obtain the attributes modified
by an open delegate to allow the server to respond to GETATTR
requests for a file which is the subject of an open delegation.
If the handle specified is not one for which the client holds a
write open delegation, an NFS4ERR_BADHANDLE error is returned.
IMPLEMENTATION
The client returns attrbits and the associated attribute values
only for attributes that it may change (change, time_modify,
object_size).
ERRORS
NFS4ERR_BADHANDLE
NFS4ERR_RESOURCE
15.2.2. Operation 4: CB_RECALL - Recall an Open Delegation
SYNOPSIS
stateid, truncate, fh -> status
ARGUMENT
struct CB_RECALL4args {
stateid4 stateid;
bool truncate;
nfs_fh4 fh;
};
RESULT
struct CB_RECALL4res {
nfsstat4 status;
};
DESCRIPTION
The CB_RECALL operation is used to begin the process of recalling
an open delegation and returning it to the server.
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.
If the handle specified is not one for which the client holds an
open delegation, an NFS4ERR_BADHANDLE error is returned.
If the stateid specified is not one corresponding to an open
delegation for the file specified by the filehandle, an
NFS4ERR_BAD_STATEID is returned.
IMPLEMENTATION
The client should reply to the callback immediately. Replying
does not complete the recall. The recall is not complete until
the delegation is returned using a DELEGRETURN.
ERRORS
NFS4ERR_BADHANDLE
NFS4ERR_BAD_STATEID
NFS4ERR_RESOURCE
16. Security Considerations
The major security feature to consider is the authentication of the
user making the request of NFS service. Consideration should also be
given to the integrity and privacy of this NFS request. These
specific issues are discussed as part of the section on "RPC and
Security Flavor".
17. IANA Considerations
17.1. Named Attribute Definition
The NFS version 4 protocol provides for the association of named
attributes to files. The name space identifiers for these attributes
are defined as string names. The protocol does not define the
specific assignment of the name space for these file attributes; the
application developer or system vendor is allowed to define the
attribute, its semantics, and the associated name. Even though this
name space will not be specifically controlled to prevent collisions,
the application developer or system vendor is strongly encouraged to
provide the name assignment and associated semantics for attributes
via an Informational RFC. This will provide for interoperability
where common interests exist.
18. RPC definition file
/*
* Copyright (C) The Internet Society (1998,1999,2000).
* All Rights Reserved.
*/
/*
* nfs4_prot.x
*
*/
%#pragma ident "@(#)nfs4_prot.x 1.97 00/06/12"
/*
* Basic typedefs for RFC1832 data type definitions
*/
typedef int int32_t;
typedef unsigned int uint32_t;
typedef hyper int64_t;
typedef unsigned hyper uint64_t;
/*
* Sizes
*/
const NFS4_FHSIZE = 128;
const NFS4_VERIFIER_SIZE = 8;
/*
* File types
*/
enum nfs_ftype4 {
NF4REG = 1, /* Regular File */
NF4DIR = 2, /* Directory */
NF4BLK = 3, /* Special File - block device */
NF4CHR = 4, /* Special File - character device */
NF4LNK = 5, /* Symbolic Link */
NF4SOCK = 6, /* Special File - socket */
NF4FIFO = 7, /* Special File - fifo */
NF4ATTRDIR = 8, /* Attribute Directory */
NF4NAMEDATTR = 9 /* Named Attribute */
};
/*
* Error status
*/
enum nfsstat4 {
NFS4_OK = 0,
NFS4ERR_PERM = 1,
NFS4ERR_NOENT = 2,
NFS4ERR_IO = 5,
NFS4ERR_NXIO = 6,
NFS4ERR_ACCES = 13,
NFS4ERR_EXIST = 17,
NFS4ERR_XDEV = 18,
NFS4ERR_NODEV = 19,
NFS4ERR_NOTDIR = 20,
NFS4ERR_ISDIR = 21,
NFS4ERR_INVAL = 22,
NFS4ERR_FBIG = 27,
NFS4ERR_NOSPC = 28,
NFS4ERR_ROFS = 30,
NFS4ERR_MLINK = 31,
NFS4ERR_NAMETOOLONG = 63,
NFS4ERR_NOTEMPTY = 66,
NFS4ERR_DQUOT = 69,
NFS4ERR_STALE = 70,
NFS4ERR_BADHANDLE = 10001,
NFS4ERR_BAD_COOKIE = 10003,
NFS4ERR_NOTSUPP = 10004,
NFS4ERR_TOOSMALL = 10005,
NFS4ERR_SERVERFAULT = 10006,
NFS4ERR_BADTYPE = 10007,
NFS4ERR_DELAY = 10008,
NFS4ERR_SAME = 10009,/* nverify says attrs same */
NFS4ERR_DENIED = 10010,/* lock unavailable */
NFS4ERR_EXPIRED = 10011,/* lock lease expired */
NFS4ERR_LOCKED = 10012,/* I/O failed due to lock */
NFS4ERR_GRACE = 10013,/* in grace period */
NFS4ERR_FHEXPIRED = 10014,/* file handle expired */
NFS4ERR_SHARE_DENIED = 10015,/* share reserve denied */
NFS4ERR_WRONGSEC = 10016,/* wrong security flavor */
NFS4ERR_CLID_INUSE = 10017,/* clientid in use */
NFS4ERR_RESOURCE = 10018,/* resource exhaustion */
NFS4ERR_MOVED = 10019,/* filesystem relocated */
NFS4ERR_NOFILEHANDLE = 10020,/* current FH is not set */
NFS4ERR_MINOR_VERS_MISMATCH = 10021,/* minor vers not supp */
NFS4ERR_STALE_CLIENTID = 10022,
NFS4ERR_STALE_STATEID = 10023,
NFS4ERR_OLD_STATEID = 10024,
NFS4ERR_BAD_STATEID = 10025,
NFS4ERR_BAD_SEQID = 10026,
NFS4ERR_NOT_SAME = 10027,/* verify - attrs not same */
NFS4ERR_LOCK_RANGE = 10028,
NFS4ERR_SYMLINK = 10029,
NFS4ERR_READDIR_NOSPC = 10030,
NFS4ERR_LEASE_MOVED = 10031
};
/*
* Basic data types
*/
typedef uint32_t bitmap4<>;
typedef uint64_t offset4;
typedef uint32_t count4;
typedef uint64_t length4;
typedef uint64_t clientid4;
typedef uint64_t stateid4;
typedef uint32_t seqid4;
typedef opaque utf8string<>;
typedef utf8string component4;
typedef component4 pathname4<>;
typedef uint64_t nfs_lockid4;
typedef uint64_t nfs_cookie4;
typedef utf8string linktext4;
typedef opaque sec_oid4<>;
typedef uint32_t qop4;
typedef uint32_t mode4;
typedef uint64_t changeid4;
typedef opaque verifier4[NFS4_VERIFIER_SIZE];
/*
* Timeval
*/
struct nfstime4 {
int64_t seconds;
uint32_t nseconds;
};
enum time_how4 {
SET_TO_SERVER_TIME4 = 0,
SET_TO_CLIENT_TIME4 = 1
};
union settime4 switch (time_how4 set_it) {
case SET_TO_CLIENT_TIME4:
nfstime4 time;
default:
void;
};
/*
* File access handle
*/
typedef opaque nfs_fh4<NFS4_FHSIZE>;
/*
* File attribute definitions
*/
/*
* FSID structure for major/minor
*/
struct fsid4 {
uint64_t major;
uint64_t minor;
};
/*
* Filesystem locations attribute for relocation/migration
*/
struct fs_location4 {
utf8string server<>;
pathname4 rootpath;
};
struct fs_locations4 {
pathname4 fs_root;
fs_location4 locations<>;
};
/*
* Various Access Control Entry definitions
*/
/*
* Mask that indicates which Access Control Entries are supported.
* Values for the fattr4_aclsupport attribute.
*/
const ACL4_SUPPORT_ALLOW_ACL = 0x00000001;
const ACL4_SUPPORT_DENY_ACL = 0x00000002;
const ACL4_SUPPORT_AUDIT_ACL = 0x00000004;
const ACL4_SUPPORT_ALARM_ACL = 0x00000008;
typedef uint32_t acetype4;
/*
* acetype4 values, others can be added as needed.
*/
const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000;
const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001;
const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002;
const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003;
/*
* ACE flag
*/
typedef uint32_t aceflag4;
/*
* ACE flag values
*/
const ACE4_FILE_INHERIT_ACE = 0x00000001;
const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002;
const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004;
const ACE4_INHERIT_ONLY_ACE = 0x00000008;
const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010;
const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020;
const ACE4_IDENTIFIER_GROUP = 0x00000040;
/*
* ACE mask
*/
typedef uint32_t acemask4;
/*
* ACE mask values
*/
const ACE4_READ_DATA = 0x00000001;
const ACE4_LIST_DIRECTORY = 0x00000001;
const ACE4_WRITE_DATA = 0x00000002;
const ACE4_ADD_FILE = 0x00000002;
const ACE4_APPEND_DATA = 0x00000004;
const ACE4_ADD_SUBDIRECTORY = 0x00000004;
const ACE4_READ_NAMED_ATTRS = 0x00000008;
const ACE4_WRITE_NAMED_ATTRS = 0x00000010;
const ACE4_EXECUTE = 0x00000020;
const ACE4_DELETE_CHILD = 0x00000040;
const ACE4_READ_ATTRIBUTES = 0x00000080;
const ACE4_WRITE_ATTRIBUTES = 0x00000100;
const ACE4_DELETE = 0x00010000;
const ACE4_READ_ACL = 0x00020000;
const ACE4_WRITE_ACL = 0x00040000;
const ACE4_WRITE_OWNER = 0x00080000;
const ACE4_SYNCHRONIZE = 0x00100000;
/*
* ACE4_GENERIC_READ -- defined as combination of
* ACE4_READ_ACL |
* ACE4_READ_DATA |
* ACE4_READ_ATTRIBUTES |
* ACE4_SYNCHRONIZE
*/
const ACE4_GENERIC_READ = 0x00120081;
/*
* ACE4_GENERIC_WRITE -- defined as combination of
* ACE4_READ_ACL |
* ACE4_WRITE_DATA |
* ACE4_WRITE_ATTRIBUTES |
* ACE4_WRITE_ACL |
* ACE4_APPEND_DATA |
* ACE4_SYNCHRONIZE
*/
const ACE4_GENERIC_WRITE = 0x00160106;
/*
* ACE4_GENERIC_EXECUTE -- defined as combination of
* ACE4_READ_ACL
* ACE4_READ_ATTRIBUTES
* ACE4_EXECUTE
* ACE4_SYNCHRONIZE
*/
const ACE4_GENERIC_EXECUTE = 0x001200A0;
/*
* Access Control Entry definition
*/
struct nfsace4 {
acetype4 type;
aceflag4 flag;
acemask4 access_mask;
utf8string who;
};
/*
* Special data/attribute associated with
* file types NF4BLK and NF4CHR.
*/
struct specdata4 {
uint32_t specdata1;
uint32_t specdata2;
};
/*
* Values for fattr4_fh_expire_type
*/
const FH4_PERSISTENT = 0x00000000;
const FH4_NOEXPIRE_WITH_OPEN = 0x00000001;
const FH4_VOLATILE_ANY = 0x00000002;
const FH4_VOL_MIGRATION = 0x00000004;
const FH4_VOL_RENAME = 0x00000008;
typedef bitmap4 fattr4_supported_attrs;
typedef nfs_ftype4 fattr4_type;
typedef uint32_t fattr4_fh_expire_type;
typedef changeid4 fattr4_change;
typedef uint64_t fattr4_size;
typedef bool fattr4_link_support;
typedef bool fattr4_symlink_support;
typedef bool fattr4_named_attr;
typedef fsid4 fattr4_fsid;
typedef bool fattr4_unique_handles;
typedef uint32_t fattr4_lease_time;
typedef nfsstat4 fattr4_rdattr_error;
typedef nfsace4 fattr4_acl<>;
typedef uint32_t fattr4_aclsupport;
typedef bool fattr4_archive;
typedef bool fattr4_cansettime;
typedef bool fattr4_case_insensitive;
typedef bool fattr4_case_preserving;
typedef bool fattr4_chown_restricted;
typedef uint64_t fattr4_fileid;
typedef uint64_t fattr4_files_avail;
typedef nfs_fh4 fattr4_filehandle;
typedef uint64_t fattr4_files_free;
typedef uint64_t fattr4_files_total;
typedef fs_locations4 fattr4_fs_locations;
typedef bool fattr4_hidden;
typedef bool fattr4_homogeneous;
typedef uint64_t fattr4_maxfilesize;
typedef uint32_t fattr4_maxlink;
typedef uint32_t fattr4_maxname;
typedef uint64_t fattr4_maxread;
typedef uint64_t fattr4_maxwrite;
typedef utf8string fattr4_mimetype;
typedef mode4 fattr4_mode;
typedef bool fattr4_no_trunc;
typedef uint32_t fattr4_numlinks;
typedef utf8string fattr4_owner;
typedef utf8string fattr4_owner_group;
typedef uint64_t fattr4_quota_avail_hard;
typedef uint64_t fattr4_quota_avail_soft;
typedef uint64_t fattr4_quota_used;
typedef specdata4 fattr4_rawdev;
typedef uint64_t fattr4_space_avail;
typedef uint64_t fattr4_space_free;
typedef uint64_t fattr4_space_total;
typedef uint64_t fattr4_space_used;
typedef bool fattr4_system;
typedef nfstime4 fattr4_time_access;
typedef settime4 fattr4_time_access_set;
typedef nfstime4 fattr4_time_backup;