[AFS3-std] Standardization of GetCapabilties RPCs for AFS3 client and services

[Jeffrey Altman]

OpenAFS as part of

http://www.openafs.org/cgi-bin/wdelta/capabilities-20030304

added two new RPCs.  The first was AFSCB_TellMeAboutYourself that
is served by the client and and the second is AFS_GetCapabilities
that is served by Viced.  At the time these interfaces were poorly
defined.  The following is a proposal that is compatible with the
existing implementations.


DATA TYPES:

The following types are already in use by existing implementations.
They are listed here for reference.

const AFS_MAX_INTERFACE_ADDR  =  32;
struct interfaceAddr {          /* for multihomed clients */
   int         numberOfInterfaces;
   afsUUID     uuid;
   afs_int32   addr_in[AFS_MAX_INTERFACE_ADDR]; /* net order */
   afs_int32   subnetmask[AFS_MAX_INTERFACE_ADDR]; /* net order */
   afs_int32   mtu[AFS_MAX_INTERFACE_ADDR]; /* MTU */
};

const AFSCAPABILITIESMAX = 196;
typedef afs_uint32 Capabilities<AFSCAPABILITIESMAX>;

Capabilities are communicated as an array of bit flags providing
6272 distinct capabilities per client or service.


RPC Names:

RXAFSCB_TellMeAboutYourself  (client)
RXAFS_GetCapabilities (file server)
AFSVol_GetCapabilities (vol server)
VL_GetCapabilities (vldb server)
PR_GetCapabilities (protection server)


RPC Descriptions (using rxgen format)

RXAFSCB_TellMeAboutYourself(
  OUT struct interfaceAddr *addr,
  OUT Capabilities *capabilities
) = 65538;

RXAFS_GetCapabilities(
  Capabilities *capabilities
) = 65540;

AFSVol_GetCapabilities(
  Capabilities *capabilities
) = to be assigned by registrar@grand.central.org;

VL_GetCapabilities(
  Capabilities *capabilities
) = to be assigned by registrar@grand.central.org;

PR_GetCapabilities(
  Capabilities *capabilities
) = to be assigned by registrar@grand.central.org;


CAPABILITY FLAGS:

Capability Flags will be registered with registrar@grand.central.org
on a per-RPC basis.  The following capabilities are already in use:

/* Viced Capability Flags */
const VICED_CAPABILITY_ERRORTRANS       = 0x0001;
const VICED_CAPABILITY_64BITFILES       = 0x0002;

/* Cache Manager Capability Flags */
const CLIENT_CAPABILITY_ERRORTRANS      = 0x0001;


IMPLEMENTATION NOTES:

Services that implement a xxxx_GetCapabilities RPC should process them
with the same semantics that are used for the xxxx_GetTime RPC.  This
will allow xxxx_GetCapabilities to be used as a replacement for
xxxx_GetTime as a ping RPC.  A ping RPC must not only return
a response for the purpose of maintaining a network route through a NAT
but must also re-establish the binding between the calling host and any
internal state maintained by the called host about the calling host.
If this requirement is ignored in the file server, for example,
callbacks with delayed breaks will not be broken in response to a
xxxx_GetCapabilities RPC.

>From the perspective of the caller, xxxx_GetCapabilities returning
RXGEN_OPCODE is an indication that the RPC is not supported and the
service is running.  However, it does not result in a binding between
the rx connection and the internally maintained host data in the OpenAFS
file server.  Therefore, an AFS Cache Manager client should fallback to
calling the xxxx_GetTime RPC if RXGEN_OPCODE is received when attempting
to ping the service.


PROPOSED USAGE OF CAPABILITY FLAGS:

Historically callers of RPCs have probed services for new or extended
functionality by calling an RPC and then falling back to an alternate
behavior if the RPC is not supported.  This has resulted in RPCs such
as xxxx_FooBar, xxxx_OldFooBar, xxxx_OldOldFooBar.  This method of
extending the functionality of AFS has a several drawbacks:

(1) there is a performance hit associated with each request when the
    desired RPC is unsupported by the service.

(2) some operations may not be safe to start unless it is known that
    the necessary RPCs are available to carry out the operations.

(3) It is not safe to cache the knowledge that the RPC is not supported
    because the client may not notice when the service is upgraded to a
    version that does support it.

It is recommended that the Capabilities be used to address these issues
as follows:

(1) xxxx_GetCapabilities should be used instead of xxxx_GetTime as the
    mechanism to ping the server to obtain its state.  As a side effect
    of the ping, the caller will refresh the known Capabilities of the
    server.  The caller will therefore always have a fresh knowledge of
    the supported functionality of the server.

(2) When knowledge of a new service is obtained, the service should be
    pinged to obtain its capabilities.

(3) The Capabilities flags when available should be used to determine
    the supported RPCs instead of probing the RPC support by issuing a
    call and checking for RXGEN_OPCODE.

(4) Instead of extending functionality by issuing a new RPC and then
    supporting both the old and new forms, RPCs should be extended by
    adding the new functions to the existing RPC and specifying a
    Capability flag.

    For example, adding Lock Upgrade and Lock Downgrade functionality
    can be performed by a combination of a extending the SetLock RPC
    and providing a Capability flag.  This will prevent new clients
    that attempt to use the functions from attempting an extra RPC call
    for each Lock Upgrade and Lock Downgrade request.

(5) In addition to advertising new functionality, the Capabilities flags
    can be used to provide hints to the caller of behavior the server
    may desire.  For example, a file server may prefer that client not
    request make SetLock requests even though the functionality is
    supported.  These hints would not be mandatory and would simply be
    a method by which desired policy can be distributed from server to
    client.


Jeffrey Altman


-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 3288 bytes
Desc: S/MIME Cryptographic Signature
Url : http://michigan-openafs-lists.central.org/archives/afs3-standardization/attachments/20060224/ff783d67/smime.bin