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

From: Chuck Lever <[email-masked]>
Date: Thu, 08 Jul 2010 11:57:09 -0400

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

---

From: "Everhart, Craig" <[email-masked]>
Date: Thu, 8 Jul 2010 12:35:27 -0400

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:[email-masked]]
> Sent: Thursday, July 08, 2010 11:57 AM
> To: [email-masked]
> Subject: [nfsv4] [FedFS] proposed ADMIN protocol procedure to enumerate
> server's NSDB store
> 
> _______________________________________________
> nfsv4 mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/nfsv4

---

From: Chuck Lever <[email-masked]>
Date: Thu, 08 Jul 2010 13:13:32 -0400

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

---

From: Nicolas Williams <[email-masked]>
Date: Thu, 8 Jul 2010 12:34:59 -0500

On Thu, Jul 08, 2010 at 01:13:32PM -0400, Chuck Lever 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.
> >
> 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.

I agree that the ADMIN server "therefore must keep" such a list, even
without an RPC for listing them.  For some implementors that might not
be a complete list, but I suppose that's not a problem we should be
concerned with here ("don't do that").

But it's worth pointing this implication out explicitly.

There's no additional implication regarding any ability to list
junctions, nor reference counting of NSDBs referred to by junctions.
But it'd be nice to have an option for listing junctions (for
implementors that can do it) and/or reference counting NSDBs (for
implementors that can do it).

Nico
--

---

From: Nicolas Williams <[email-masked]>
Date: Thu, 8 Jul 2010 12:42:28 -0500

>       FEDFS_GET_NSDB_NAMES request is no longer valid.

NOT_SAME seems insufficiently descriptive.  How about
FEDFS_ERR_NSDB_INVALID_COOKIE?

>    unchanged from the previous failed FEDFS_GET_NSDB_NAMES request).

Why should one tell the server a max reply size instead of a max number
of NSDBs whose params to return?

Why shouldn't the server decide how many NSDBs to list in a single RPC
result instead?

Nico
--

---

From: Chuck Lever <[email-masked]>
Date: Thu, 08 Jul 2010 14:41:49 -0400

> FEDFS_ERR_NSDB_INVALID_COOKIE?

Following the precedent set by the authors of the ADMIN protocol draft, 
I appropriated NOT_SAME from 5661's READDIR procedure.

> of NSDBs whose params to return?

Because there is no limit on the size of a single NSDB name.

> Why shouldn't the server decide how many NSDBs to list in a single RPC

The receiving end (the client) may have limited space to receive NSDB 
name information.

---

From: Nicolas Williams <[email-masked]>
Date: Thu, 8 Jul 2010 14:59:48 -0500

On Thu, Jul 08, 2010 at 02:41:49PM -0400, Chuck Lever wrote:
> The receiving end (the client) may have limited space to receive
> NSDB name information.

Clients could cope even without this maxcount thing.  E.g., the client
app could double its buffer and retry.  But I see that NFSv4 already
uses this same maxcount approach, so this is consistent with NFSv4, so
never mind.