Tech-invite   World Map
3GPPspecs     Glossaries     T+       IETF     RFCs     Groups     SIP     ABNFs

RFC 7862

 
 
 

Network File System (NFS) Version 4 Minor Version 2 Protocol

Part 4 of 6, p. 54 to 64
Prev Section       Next Section

 


prevText      Top      ToC       Page 54 
12.  New File Attributes

12.1.  New RECOMMENDED Attributes - List and Definition References

   The list of new RECOMMENDED attributes appears in Table 4.  The
   meanings of the columns of the table are:

   Name:  The name of the attribute.

   Id:  The number assigned to the attribute.  In the event of conflicts
      between the assigned number and [RFC7863], the latter is
      authoritative, but in such an event, it should be resolved with
      errata to this document and/or [RFC7863].  See [IESG08] for the
      errata process.

   Data Type:  The XDR data type of the attribute.

   Acc:  Access allowed to the attribute.

      R  means read-only (GETATTR may retrieve, SETATTR may not set).

      W  means write-only (SETATTR may set, GETATTR may not retrieve).

      R W   means read/write (GETATTR may retrieve, SETATTR may set).

   Defined in:  The section of this specification that describes the
      attribute.

   +------------------+----+-------------------+-----+----------------+
   | Name             | Id | Data Type         | Acc | Defined in     |
   +------------------+----+-------------------+-----+----------------+
   | clone_blksize    | 77 | uint32_t          | R   | Section 12.2.1 |
   | space_freed      | 78 | length4           | R   | Section 12.2.2 |
   | change_attr_type | 79 | change_attr_type4 | R   | Section 12.2.3 |
   | sec_label        | 80 | sec_label4        | R W | Section 12.2.4 |
   +------------------+----+-------------------+-----+----------------+

                    Table 4: New RECOMMENDED Attributes

12.2.  Attribute Definitions

12.2.1.  Attribute 77: clone_blksize

   The clone_blksize attribute indicates the granularity of a CLONE
   operation.

Top      Up      ToC       Page 55 
12.2.2.  Attribute 78: space_freed

   space_freed gives the number of bytes freed if the file is deleted.
   This attribute is read-only and is of type length4.  It is a per-file
   attribute.

12.2.3.  Attribute 79: change_attr_type

   <CODE BEGINS>

   enum change_attr_type4 {
              NFS4_CHANGE_TYPE_IS_MONOTONIC_INCR         = 0,
              NFS4_CHANGE_TYPE_IS_VERSION_COUNTER        = 1,
              NFS4_CHANGE_TYPE_IS_VERSION_COUNTER_NOPNFS = 2,
              NFS4_CHANGE_TYPE_IS_TIME_METADATA          = 3,
              NFS4_CHANGE_TYPE_IS_UNDEFINED              = 4
   };

   <CODE ENDS>

   change_attr_type is a per-file system attribute that enables the
   NFSv4.2 server to provide additional information about how it expects
   the change attribute value to evolve after the file data or metadata
   has changed.  While Section 5.4 of [RFC5661] discusses
   per-file system attributes, it is expected that the value of
   change_attr_type will not depend on the value of "homogeneous" and
   will only change in the event of a migration.

   NFS4_CHANGE_TYPE_IS_MONOTONIC_INCR:  The change attribute value MUST
      monotonically increase for every atomic change to the file
      attributes, data, or directory contents.

   NFS4_CHANGE_TYPE_IS_VERSION_COUNTER:  The change attribute value MUST
      be incremented by one unit for every atomic change to the file
      attributes, data, or directory contents.  This property is
      preserved when writing to pNFS data servers.

   NFS4_CHANGE_TYPE_IS_VERSION_COUNTER_NOPNFS:  The change attribute
      value MUST be incremented by one unit for every atomic change to
      the file attributes, data, or directory contents.  In the case
      where the client is writing to pNFS data servers, the number of
      increments is not guaranteed to exactly match the number of
      WRITEs.

Top      Up      ToC       Page 56 
   NFS4_CHANGE_TYPE_IS_TIME_METADATA:  The change attribute is
      implemented as suggested in [RFC7530] in terms of the
      time_metadata attribute.

   NFS4_CHANGE_TYPE_IS_UNDEFINED:  The change attribute does not take
      values that fit into any of these categories.

   If either NFS4_CHANGE_TYPE_IS_MONOTONIC_INCR,
   NFS4_CHANGE_TYPE_IS_VERSION_COUNTER, or
   NFS4_CHANGE_TYPE_IS_TIME_METADATA is set, then the client knows at
   the very least that the change attribute is monotonically increasing,
   which is sufficient to resolve the question of which value is the
   most recent.

   If the client sees the value NFS4_CHANGE_TYPE_IS_TIME_METADATA, then
   by inspecting the value of the "time_delta" attribute it additionally
   has the option of detecting rogue server implementations that use
   time_metadata in violation of the specification.

   If the client sees NFS4_CHANGE_TYPE_IS_VERSION_COUNTER, it has the
   ability to predict what the resulting change attribute value should
   be after a COMPOUND containing a SETATTR, WRITE, or CREATE.  This
   again allows it to detect changes made in parallel by another client.
   The value NFS4_CHANGE_TYPE_IS_VERSION_COUNTER_NOPNFS permits the
   same, but only if the client is not doing pNFS WRITEs.

   Finally, if the server does not support change_attr_type or if
   NFS4_CHANGE_TYPE_IS_UNDEFINED is set, then the server SHOULD make an
   effort to implement the change attribute in terms of the
   time_metadata attribute.

12.2.4.  Attribute 80: sec_label

   <CODE BEGINS>

   typedef uint32_t  policy4;

   struct labelformat_spec4 {
           policy4 lfs_lfs;
           policy4 lfs_pi;
   };

   struct sec_label4 {
           labelformat_spec4       slai_lfs;
           opaque                  slai_data<>;
   };

   <CODE ENDS>

Top      Up      ToC       Page 57 
   The FATTR4_SEC_LABEL contains an array of two components, with the
   first component being an LFS.  It serves to provide the receiving end
   with the information necessary to translate the security attribute
   into a form that is usable by the endpoint.  Label Formats assigned
   an LFS may optionally choose to include a Policy Identifier field to
   allow for complex policy deployments.  The LFS and the Security Label
   Format Selection Registry are described in detail in [RFC7569].  The
   translation used to interpret the security attribute is not specified
   as part of the protocol, as it may depend on various factors.  The
   second component is an opaque section that contains the data of the
   attribute.  This component is dependent on the MAC model to interpret
   and enforce.

   In particular, it is the responsibility of the LFS specification to
   define a maximum size for the opaque section, slai_data<>.  When
   creating or modifying a label for an object, the client needs to be
   guaranteed that the server will accept a label that is sized
   correctly.  By both client and server being part of a specific MAC
   model, the client will be aware of the size.

13.  Operations: REQUIRED, RECOMMENDED, or OPTIONAL

   Tables 5 and 6 summarize the operations of the NFSv4.2 protocol and
   the corresponding designations of REQUIRED, RECOMMENDED, and OPTIONAL
   to implement or MUST NOT implement.  The "MUST NOT implement"
   designation is reserved for those operations that were defined in
   either NFSv4.0 or NFSv4.1 and MUST NOT be implemented in NFSv4.2.

   For the most part, the REQUIRED, RECOMMENDED, or OPTIONAL designation
   for operations sent by the client is for the server implementation.
   The client is generally required to implement the operations needed
   for the operating environment that it serves.  For example, a
   read-only NFSv4.2 client would have no need to implement the WRITE
   operation and is not required to do so.

   The REQUIRED or OPTIONAL designation for callback operations sent by
   the server is for both the client and server.  Generally, the client
   has the option of creating the backchannel and sending the operations
   on the forechannel that will be a catalyst for the server sending
   callback operations.  A partial exception is CB_RECALL_SLOT; the only
   way the client can avoid supporting this operation is by not creating
   a backchannel.

Top      Up      ToC       Page 58 
   Since this is a summary of the operations and their designation,
   there are subtleties that are not presented here.  Therefore, if
   there is a question regarding implementation requirements, the
   operation descriptions themselves must be consulted, along with other
   relevant explanatory text within either this specification or the
   NFSv4.1 specification [RFC5661].

   The abbreviations used in the second and third columns of Tables 5
   and 6 are defined as follows:

   REQ:  REQUIRED to implement

   REC:  RECOMMENDED to implement

   OPT:  OPTIONAL to implement

   MNI:  MUST NOT implement

   For the NFSv4.2 features that are OPTIONAL, the operations that
   support those features are OPTIONAL, and the server MUST return
   NFS4ERR_NOTSUPP in response to the client's use of those operations
   when those operations are not implemented by the server.  If an
   OPTIONAL feature is supported, it is possible that a set of
   operations related to the feature become REQUIRED to implement.  The
   third column of the tables designates the feature(s) and if the
   operation is REQUIRED or OPTIONAL in the presence of support for the
   feature.

   The OPTIONAL features identified and their abbreviations are as
   follows:

   pNFS:  Parallel NFS

   FDELG:  File Delegations

   DDELG:  Directory Delegations

   COPYra:  Intra-server Server-Side Copy

   COPYer:  Inter-server Server-Side Copy

   ADB:  Application Data Blocks

Top      Up      ToC       Page 59 
   +----------------------+--------------------+-----------------------+
   | Operation            | REQ, REC, OPT, or  | Feature (REQ, REC, or |
   |                      | MNI                | OPT)                  |
   +----------------------+--------------------+-----------------------+
   | ACCESS               | REQ                |                       |
   | ALLOCATE             | OPT                |                       |
   | BACKCHANNEL_CTL      | REQ                |                       |
   | BIND_CONN_TO_SESSION | REQ                |                       |
   | CLONE                | OPT                |                       |
   | CLOSE                | REQ                |                       |
   | COMMIT               | REQ                |                       |
   | COPY                 | OPT                | COPYer (REQ), COPYra  |
   |                      |                    | (REQ)                 |
   | COPY_NOTIFY          | OPT                | COPYer (REQ)          |
   | CREATE               | REQ                |                       |
   | CREATE_SESSION       | REQ                |                       |
   | DEALLOCATE           | OPT                |                       |
   | DELEGPURGE           | OPT                | FDELG (REQ)           |
   | DELEGRETURN          | OPT                | FDELG, DDELG, pNFS    |
   |                      |                    | (REQ)                 |
   | DESTROY_CLIENTID     | REQ                |                       |
   | DESTROY_SESSION      | REQ                |                       |
   | EXCHANGE_ID          | REQ                |                       |
   | FREE_STATEID         | REQ                |                       |
   | GETATTR              | REQ                |                       |
   | GETDEVICEINFO        | OPT                | pNFS (REQ)            |
   | GETDEVICELIST        | MNI                | pNFS (MNI)            |
   | GETFH                | REQ                |                       |
   | GET_DIR_DELEGATION   | OPT                | DDELG (REQ)           |
   | ILLEGAL              | REQ                |                       |
   | IO_ADVISE            | OPT                |                       |
   | LAYOUTCOMMIT         | OPT                | pNFS (REQ)            |
   | LAYOUTERROR          | OPT                | pNFS (OPT)            |
   | LAYOUTGET            | OPT                | pNFS (REQ)            |
   | LAYOUTRETURN         | OPT                | pNFS (REQ)            |
   | LAYOUTSTATS          | OPT                | pNFS (OPT)            |
   | LINK                 | OPT                |                       |
   | LOCK                 | REQ                |                       |
   | LOCKT                | REQ                |                       |
   | LOCKU                | REQ                |                       |
   | LOOKUP               | REQ                |                       |
   | LOOKUPP              | REQ                |                       |
   | NVERIFY              | REQ                |                       |
   | OFFLOAD_CANCEL       | OPT                | COPYer (OPT), COPYra  |
   |                      |                    | (OPT)                 |
   | OFFLOAD_STATUS       | OPT                | COPYer (OPT), COPYra  |
   |                      |                    | (OPT)                 |

Top      Up      ToC       Page 60 
   | OPEN                 | REQ                |                       |
   | OPENATTR             | OPT                |                       |
   | OPEN_CONFIRM         | MNI                |                       |
   | OPEN_DOWNGRADE       | REQ                |                       |
   | PUTFH                | REQ                |                       |
   | PUTPUBFH             | REQ                |                       |
   | PUTROOTFH            | REQ                |                       |
   | READ                 | REQ                |                       |
   | READDIR              | REQ                |                       |
   | READLINK             | OPT                |                       |
   | READ_PLUS            | OPT                |                       |
   | RECLAIM_COMPLETE     | REQ                |                       |
   | RELEASE_LOCKOWNER    | MNI                |                       |
   | REMOVE               | REQ                |                       |
   | RENAME               | REQ                |                       |
   | RENEW                | MNI                |                       |
   | RESTOREFH            | REQ                |                       |
   | SAVEFH               | REQ                |                       |
   | SECINFO              | REQ                |                       |
   | SECINFO_NO_NAME      | REC                | pNFS file layout      |
   |                      |                    | (REQ)                 |
   | SEEK                 | OPT                |                       |
   | SEQUENCE             | REQ                |                       |
   | SETATTR              | REQ                |                       |
   | SETCLIENTID          | MNI                |                       |
   | SETCLIENTID_CONFIRM  | MNI                |                       |
   | SET_SSV              | REQ                |                       |
   | TEST_STATEID         | REQ                |                       |
   | VERIFY               | REQ                |                       |
   | WANT_DELEGATION      | OPT                | FDELG (OPT)           |
   | WRITE                | REQ                |                       |
   | WRITE_SAME           | OPT                | ADB (REQ)             |
   +----------------------+--------------------+-----------------------+

                            Table 5: Operations

Top      Up      ToC       Page 61 
   +-------------------------+------------------+----------------------+
   | Operation               | REQ, REC, OPT,   | Feature (REQ, REC,   |
   |                         | or MNI           | or OPT)              |
   +-------------------------+------------------+----------------------+
   | CB_GETATTR              | OPT              | FDELG (REQ)          |
   | CB_ILLEGAL              | REQ              |                      |
   | CB_LAYOUTRECALL         | OPT              | pNFS (REQ)           |
   | CB_NOTIFY               | OPT              | DDELG (REQ)          |
   | CB_NOTIFY_DEVICEID      | OPT              | pNFS (OPT)           |
   | CB_NOTIFY_LOCK          | OPT              |                      |
   | CB_OFFLOAD              | OPT              | COPYer (REQ), COPYra |
   |                         |                  | (REQ)                |
   | CB_PUSH_DELEG           | OPT              | FDELG (OPT)          |
   | CB_RECALL               | OPT              | FDELG, DDELG, pNFS   |
   |                         |                  | (REQ)                |
   | CB_RECALL_ANY           | OPT              | FDELG, DDELG, pNFS   |
   |                         |                  | (REQ)                |
   | CB_RECALL_SLOT          | REQ              |                      |
   | CB_RECALLABLE_OBJ_AVAIL | OPT              | DDELG, pNFS (REQ)    |
   | CB_SEQUENCE             | OPT              | FDELG, DDELG, pNFS   |
   |                         |                  | (REQ)                |
   | CB_WANTS_CANCELLED      | OPT              | FDELG, DDELG, pNFS   |
   |                         |                  | (REQ)                |
   +-------------------------+------------------+----------------------+

                       Table 6: Callback Operations

14.  Modifications to NFSv4.1 Operations

14.1.  Operation 42: EXCHANGE_ID - Instantiate the client ID

14.1.1.  ARGUMENT

   <CODE BEGINS>

      /* new */
      const EXCHGID4_FLAG_SUPP_FENCE_OPS      = 0x00000004;

   <CODE ENDS>

14.1.2.  RESULT

      Unchanged

Top      Up      ToC       Page 62 
14.1.3.  MOTIVATION

   Enterprise applications require guarantees that an operation has
   either aborted or completed.  NFSv4.1 provides this guarantee as long
   as the session is alive: simply send a SEQUENCE operation on the same
   slot with a new sequence number, and the successful return of
   SEQUENCE indicates that the previous operation has completed.
   However, if the session is lost, there is no way to know when any
   operations in progress have aborted or completed.  In hindsight, the
   NFSv4.1 specification should have mandated that DESTROY_SESSION
   either abort or complete all outstanding operations.

14.1.4.  DESCRIPTION

   A client SHOULD request the EXCHGID4_FLAG_SUPP_FENCE_OPS capability
   when it sends an EXCHANGE_ID operation.  The server SHOULD set this
   capability in the EXCHANGE_ID reply whether the client requests it or
   not.  It is the server's return that determines whether this
   capability is in effect.  When it is in effect, the following will
   occur:

   o  The server will not reply to any DESTROY_SESSION invoked with the
      client ID until all operations in progress are completed or
      aborted.

   o  The server will not reply to subsequent EXCHANGE_ID operations
      invoked on the same client owner with a new verifier until all
      operations in progress on the client ID's session are completed or
      aborted.

   o  In implementations where the NFS server is deployed as a cluster,
      it does support client ID trunking, and the
      EXCHGID4_FLAG_SUPP_FENCE_OPS capability is enabled, then a
      session ID created on one node of the storage cluster MUST be
      destroyable via DESTROY_SESSION.  In addition, DESTROY_CLIENTID
      and an EXCHANGE_ID with a new verifier affect all sessions,
      regardless of what node the sessions were created on.

Top      Up      ToC       Page 63 
14.2.  Operation 48: GETDEVICELIST - Get all device mappings for a file
       system

14.2.1.  ARGUMENT

   <CODE BEGINS>

   struct GETDEVICELIST4args {
           /* CURRENT_FH: object belonging to the file system */
           layouttype4     gdla_layout_type;

           /* number of device IDs to return */
           count4          gdla_maxdevices;

           nfs_cookie4     gdla_cookie;
           verifier4       gdla_cookieverf;
   };

   <CODE ENDS>

14.2.2.  RESULT

   <CODE BEGINS>

   struct GETDEVICELIST4resok {
           nfs_cookie4             gdlr_cookie;
           verifier4               gdlr_cookieverf;
           deviceid4               gdlr_deviceid_list<>;
           bool                    gdlr_eof;
   };

   union GETDEVICELIST4res switch (nfsstat4 gdlr_status) {
   case NFS4_OK:
           GETDEVICELIST4resok     gdlr_resok4;
   default:
           void;
   };

   <CODE ENDS>

14.2.3.  MOTIVATION

   The GETDEVICELIST operation was introduced in [RFC5661] specifically
   to request a list of devices at file system mount time from block
   layout type servers.  However, the use of the GETDEVICELIST operation
   introduces a race condition versus notification about changes to pNFS
   device IDs as provided by CB_NOTIFY_DEVICEID.  Implementation
   experience with block layout servers has shown that there is no need

Top      Up      ToC       Page 64 
   for GETDEVICELIST.  Clients have to be able to request new devices
   using GETDEVICEINFO at any time in response to either a new deviceid
   in LAYOUTGET results or the CB_NOTIFY_DEVICEID callback operation.

14.2.4.  DESCRIPTION

   Clients and servers MUST NOT implement the GETDEVICELIST operation.



(page 64 continued on part 5)

Next Section