Tech-invite3GPPspaceIETFspace
96959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 3010

NFS version 4 Protocol

Pages: 212
Obsoleted by:  3530
Part 7 of 8 – Pages 150 to 174
First   Prev   Next

ToP   noToC   RFC3010 - Page 150   prevText

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.
ToP   noToC   RFC3010 - Page 151
   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
ToP   noToC   RFC3010 - Page 152
      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
ToP   noToC   RFC3010 - Page 153
      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
ToP   noToC   RFC3010 - Page 154
      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
ToP   noToC   RFC3010 - Page 155
      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
ToP   noToC   RFC3010 - Page 156
      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)
ToP   noToC   RFC3010 - Page 157
               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
ToP   noToC   RFC3010 - Page 158
      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; };
ToP   noToC   RFC3010 - Page 159
   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
ToP   noToC   RFC3010 - Page 160
      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
ToP   noToC   RFC3010 - Page 161
      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
ToP   noToC   RFC3010 - Page 162
      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.
ToP   noToC   RFC3010 - Page 163
      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; };
ToP   noToC   RFC3010 - Page 164
   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; };
ToP   noToC   RFC3010 - Page 165
   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
ToP   noToC   RFC3010 - Page 166
      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; };
ToP   noToC   RFC3010 - Page 167
   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
ToP   noToC   RFC3010 - Page 168
      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:
ToP   noToC   RFC3010 - Page 169
               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
ToP   noToC   RFC3010 - Page 170
      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.
ToP   noToC   RFC3010 - Page 171

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.
ToP   noToC   RFC3010 - Page 172
      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; };
ToP   noToC   RFC3010 - Page 173
   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.
ToP   noToC   RFC3010 - Page 174
      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.


(next page on part 8)

Next Section