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

["Everhart, Craig" <[e-mail]>]

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.

		Craig

> -----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