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

[Chuck Lever <[e-mail]>]

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