Re: [nfsv4] [FedFS] proposed ADMIN protocol procedure to enumerate server's NSDB store

[Chuck Lever <[e-mail]>]

On 07/ 8/10 12:35 PM, Everhart, Craig wrote:
> Have I simply forgotten precisely why this is being proposed?  (Wouldn't be a surprise, here in vacation season.)
>
> My naïve mental model for an NFSv4 server would not necessarily include a data structure that would match the thing being queried in this op.  I'm not sure of the value-add of trying to include it.
>
> I'm sure we can discuss later today, but a written record is *so* handy.

See below:

"Such a procedure can be used to check for stale NSDB name entries or
misspellings, or to generate a menu of NSDB names in a graphical ADMIN
client (ie for browsing the NSDB list on a server)."

The ADMIN server, not the NFSv4 server, maintains the NSDB list.  Given 
that FEDFS_CREATE_JUNCTION must fail if the ADMIN server doesn't have 
connection information for the presented NSDB, the ADMIN server 
therefore must keep a permanent list of NSDB names.

This has been discussed before, briefly, but I'm not sure the discussion 
ever made it to meeting minutes.

>> -----Original Message-----
>> From: Chuck Lever [mailto:[e-mail]]
>> Sent: Thursday, July 08, 2010 11:57 AM
>> To: [e-mail]
>> Subject: [nfsv4] [FedFS] proposed ADMIN protocol procedure to enumerate
>> server's NSDB store
>>
>> For discussion during today's FedFS phone call
>>
>> I.     Description of intent for FEDFS_GET_NSDB_NAMES
>>
>> The operation will return a list of NSDB information that was
>> previously
>> sent to the ADMIN server via FEDFS_SET_NSDB_PARAMS.  One list entry is
>> returned for each NSDB.  Each list entry is a FedFsNsdbName.
>>
>> A maxcount field is used to manage the amount of information that is
>> returned in a single RPC.  To obtain the entire NSDB list stored on an
>> ADMIN server, clients must potentially send multiple
>> FEDFS_GET_NSDB_NAMES requests.  A cookie/verifier pair is used as a
>> cursor to iterate over the NSDB list.
>>
>> Such a procedure can be used to check for stale NSDB entries or
>> misspellings, or to generate a menu of NSDB names in a graphical ADMIN
>> client (ie for browsing the NSDB list on a server).
>>
>>
>> II.     Proposed new data types, based on draft 05
>>
>>      enum FedFsStatus {
>>         ...
>>       FEDFS_ERR_NSDB_PARAMS       = 24,
>>       FEDFS_ERR_NSDB_NOT_SAME     = 25,
>>       FEDFS_ERR_NSDB_TOO_SMALL    = 26
>>      };
>>
>>      typedef opaque                   FedFsVerifier[8];
>>
>>      struct FedFsGetNsdbNamesArgs {
>>              FedFsVerifier            verifier;
>>              unsigned int             cookie;
>>              unsigned int             maxcount;
>>      };
>>
>>      struct FedFsGetNsdbNamesResOk {
>>              FedFsVerifier            verifier;
>>              unsigned int             cookie;
>>              FedFsNsdbName            names<>;
>>      };
>>
>>      struct FedFsGetNsdbNamesResTS {
>>              FedFsVerifier            verifier;
>>              unsigned int             cookie;
>>              unsigned int             maxcount;
>>      };
>>
>>      union FedFsGetNsdbNamesRes switch (FedFsStatus status) {
>>       case FEDFS_OK:
>>              FedFsGetNsdbNamesResOk   resok;
>>       case FEDFS_ERR_NSDB_TOO_SMALL:
>>              FedFsGetNsdbNamesResTS   restoosmall;
>>       default:
>>              void;
>>      };
>>
>>      FedFsGetNsdbNamesRes FEDFS_GET_NSDB_NAMES(
>>                   FedFsGetNsdbNamesArgs) = 10;
>>
>>
>> III.     Proposed new language, based on draft 05 and RFC 5661
>>
>> 3.     Error Values
>>
>>        ...
>>
>>      FEDFS_ERR_NSDB_PARAMS  The fileserver does not have any connection
>>         parameters on record for the specified NSDB.
>>
>>      FEDFS_ERR_NSDB_NOT_SAME  The cookie/verifier pair passed in a
>>         FEDFS_GET_NSDB_NAMES request is no longer valid.
>>
>>      FEDFS_ERR_NSDB_TOO_SMALL  The caller specified a maxcount that is
>>         not large enough to hold the next FedFsNsdbName in a
>>         FEDFS_GET_NSDB_NAMES result
>>
>> 5.10.  FEDFS_GET_NSDB_NAMES
>>
>>      This operation retrieves a partial or whole list of NSDBs that are
>>      on record with this server.  The server's NSDB list includes NSDBs
>>      that were previously registered with this ADMIN server via the
>>      FEDFS_SET_NSDB_PARAMS operation.
>>
>>      This operation returns only the FedFsNsdbName of each registered
>>      NSDB.  Clients can retrieve other information related to any of
>>      the returned NSDBs by subsequently issuing FEDFS_GET_NSDB_PARAMS
>>      requests for interesting NSDBs.  Viewing the list of on-record
>>      NSDBs MAY be a less privileged operation than viewing NSDB
>>      connection parameters returned by FEDFS_GET_NSDB_PARAMS.
>>
>>      The arguments contain a cookie value that represents where the
>>      FEDFS_GET_NSDB_NAMES operation should start in the NSDB list.  For
>>      the initial FEDFS_GET_NSDB_NAMES request, both the cookie value and
>>      the verifier MUST be set to zero to start reading at the beginning
>>      of the server's NSDB list.  For subsequent FEDFS_GET_NSDB_NAMES
>>      requests, the client specifies the cookie and verifier values
>>      returned by the server from a previous FEDFS_GET_NSDB_NAMES request.
>>
>>      The cookie value is meaningful only to the server, which uses it
>>      as a cursor for its NSDB name list.  The cookie value may be cached
>>      by the client, but the client MUST treat cookie values as entirely
>>      opaque.  Ideally, the cookie value SHOULD NOT change if the NSDB
>> list
>>      is modified, since the client may be caching these values.
>>
>>      The server uses the verifier field to validate the cookie value. On
>>      subsequent FEDFS_GET_NSDB_NAMES requests, the verifier field in the
>>      request's arguments must match the verifier returned by the
>>      FEDFS_GET_NSDB_NAMES request in which the cookie was acquired.  If
>>      the server determines that the verifier is no longer valid, the
>> error
>>      FEDFS_ERR_NSDB_NOT_SAME MUST be returned.  To continue reading the
>>      list, the client must issue a fresh initial FEDFS_GET_NSDB_NAMES
>>      request, as described above.
>>
>>      The verifier may be used by the ADMIN 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/verifier pair.  The server SHOULD make every effort
>>      to avoid this condition since the client might be unable to
>> properly
>>      handle this type of failure.
>>
>>      The maxcount field is a hint of the maximum number of bytes of NSDB
>>      information that should be returned in the reply.  This value
>>      represents the total length of NSDB names, after XDR encoding, and
>>      not the length of the native format of the NSDB names on the ADMIN
>>      server.  If the server is unable to fit a single name within the
>>      maxcount limit, the error FEDFS_ERR_NSDB_TOO_SMALL MUST be returned.
>>      The number of XDR bytes needed to return the next name MUST be
>> placed
>>      in the reply's maxcount field.  The server also returns a
>>      cookie/verifier pair that is needed to read this value (usually
>>      unchanged from the previous failed FEDFS_GET_NSDB_NAMES request).
>>
>>      When there are no more NSDB names to return, the server sets the
>>      cookie and verifier reply fields to zero.  If the ADMIN server's
>> NSDB
>>      list is empty on the initial FEDFS_GET_NSDB_NAMES request, the
>> server
>>      MUST return an empty names list and set the cookie and verifier
>> reply
>>      fields to zero.
>>
>>      On success, this operation returns FEDFS_OK, a list of
>>      FedFsNsdbNames, and a cookie/verifier pair that the client can use
>>      to retrieve the next list entries.
>>
>>      On failure, an error value indicating the type of error is returned.
>>      The operation MAY return FEDFS_ERR_ACCESS if the operation's
>>      associated user does not have sufficient permissions to view NSDB
>>      names.
>>
>> --
>> chuck[dot]lever[at]oracle[dot]come
>> _______________________________________________
>> nfsv4 mailing list
>> [e-mail]
>> https://www.ietf.org/mailman/listinfo/nfsv4