[AFS3-std] Standardization of GetCapabilties RPCs for AFS3 client
and services
Jeffrey Altman
jaltman@secure-endpoints.com
Fri, 24 Feb 2006 18:16:39 -0500
This is a cryptographically signed message in MIME format.
--------------ms080403080000090106070401
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: 7bit
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
--------------ms080403080000090106070401
Content-Type: application/x-pkcs7-signature; name="smime.p7s"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime.p7s"
Content-Description: S/MIME Cryptographic Signature
MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAQAAoIIJXzCC
AwowggJzoAMCAQICAw7NrTANBgkqhkiG9w0BAQQFADBiMQswCQYDVQQGEwJaQTElMCMGA1UE
ChMcVGhhd3RlIENvbnN1bHRpbmcgKFB0eSkgTHRkLjEsMCoGA1UEAxMjVGhhd3RlIFBlcnNv
bmFsIEZyZWVtYWlsIElzc3VpbmcgQ0EwHhcNMDUwNTI3MTc0NzU3WhcNMDYwNTI3MTc0NzU3
WjBzMQ8wDQYDVQQEEwZBbHRtYW4xFTATBgNVBCoTDEplZmZyZXkgRXJpYzEcMBoGA1UEAxMT
SmVmZnJleSBFcmljIEFsdG1hbjErMCkGCSqGSIb3DQEJARYcamFsdG1hbkBzZWN1cmUtZW5k
cG9pbnRzLmNvbTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKjPyrF+rdjOUSK/
bWwZHdx5p1+y6iiCd4vvYEVDxouYFp5C/fZEWm5n45ubBUbMSUI1MAZN6ooEoH09UTj6BXhM
S8B987ls81dKOIUphTF2jOzq8gsFmeA15yHMRAD20LqUWeLyvYk8FCNQw+dsKMMhX+WdsxOm
RY/1jPkJL6oN8kEwoUFkOX9/OfWWh6oFnV6faiEHUKDMFubsb9X0KVD8iIeR7Cxz7i4kXqRX
wMlp2fyoxcDIJrBaTY8nA++g3p34IkWt1a5po6g683nIgSnGpwYIwuJheBqSEZfLYWa+1KdD
6Sn27Ud94GqUvPVG5jC6zVC5EJ2aWuoAu+nNuV8CAwEAAaM5MDcwJwYDVR0RBCAwHoEcamFs
dG1hbkBzZWN1cmUtZW5kcG9pbnRzLmNvbTAMBgNVHRMBAf8EAjAAMA0GCSqGSIb3DQEBBAUA
A4GBADtvO//tjiAV6VJGtoNtrl34mB5jGyGTiotzw8riB6zz0GvY11bcWDmp6JKif+pVG+8L
IySDosbuva13qu2HwYUxBmWc7CoNd2k9kRlcrfbDUTTrGOZK8qyqNqT3gQZTAa9ZnUI0su9G
y/n2o5bQcaYdqR3htNrpvdLSPOWhILOXMIIDCjCCAnOgAwIBAgIDDs2tMA0GCSqGSIb3DQEB
BAUAMGIxCzAJBgNVBAYTAlpBMSUwIwYDVQQKExxUaGF3dGUgQ29uc3VsdGluZyAoUHR5KSBM
dGQuMSwwKgYDVQQDEyNUaGF3dGUgUGVyc29uYWwgRnJlZW1haWwgSXNzdWluZyBDQTAeFw0w
NTA1MjcxNzQ3NTdaFw0wNjA1MjcxNzQ3NTdaMHMxDzANBgNVBAQTBkFsdG1hbjEVMBMGA1UE
KhMMSmVmZnJleSBFcmljMRwwGgYDVQQDExNKZWZmcmV5IEVyaWMgQWx0bWFuMSswKQYJKoZI
hvcNAQkBFhxqYWx0bWFuQHNlY3VyZS1lbmRwb2ludHMuY29tMIIBIjANBgkqhkiG9w0BAQEF
AAOCAQ8AMIIBCgKCAQEAqM/KsX6t2M5RIr9tbBkd3HmnX7LqKIJ3i+9gRUPGi5gWnkL99kRa
bmfjm5sFRsxJQjUwBk3qigSgfT1ROPoFeExLwH3zuWzzV0o4hSmFMXaM7OryCwWZ4DXnIcxE
APbQupRZ4vK9iTwUI1DD52wowyFf5Z2zE6ZFj/WM+Qkvqg3yQTChQWQ5f3859ZaHqgWdXp9q
IQdQoMwW5uxv1fQpUPyIh5HsLHPuLiRepFfAyWnZ/KjFwMgmsFpNjycD76DenfgiRa3Vrmmj
qDrzeciBKcanBgjC4mF4GpIRl8thZr7Up0PpKfbtR33gapS89UbmMLrNULkQnZpa6gC76c25
XwIDAQABozkwNzAnBgNVHREEIDAegRxqYWx0bWFuQHNlY3VyZS1lbmRwb2ludHMuY29tMAwG
A1UdEwEB/wQCMAAwDQYJKoZIhvcNAQEEBQADgYEAO287/+2OIBXpUka2g22uXfiYHmMbIZOK
i3PDyuIHrPPQa9jXVtxYOanokqJ/6lUb7wsjJIOixu69rXeq7YfBhTEGZZzsKg13aT2RGVyt
9sNRNOsY5kryrKo2pPeBBlMBr1mdQjSy70bL+fajltBxph2pHeG02um90tI85aEgs5cwggM/
MIICqKADAgECAgENMA0GCSqGSIb3DQEBBQUAMIHRMQswCQYDVQQGEwJaQTEVMBMGA1UECBMM
V2VzdGVybiBDYXBlMRIwEAYDVQQHEwlDYXBlIFRvd24xGjAYBgNVBAoTEVRoYXd0ZSBDb25z
dWx0aW5nMSgwJgYDVQQLEx9DZXJ0aWZpY2F0aW9uIFNlcnZpY2VzIERpdmlzaW9uMSQwIgYD
VQQDExtUaGF3dGUgUGVyc29uYWwgRnJlZW1haWwgQ0ExKzApBgkqhkiG9w0BCQEWHHBlcnNv
bmFsLWZyZWVtYWlsQHRoYXd0ZS5jb20wHhcNMDMwNzE3MDAwMDAwWhcNMTMwNzE2MjM1OTU5
WjBiMQswCQYDVQQGEwJaQTElMCMGA1UEChMcVGhhd3RlIENvbnN1bHRpbmcgKFB0eSkgTHRk
LjEsMCoGA1UEAxMjVGhhd3RlIFBlcnNvbmFsIEZyZWVtYWlsIElzc3VpbmcgQ0EwgZ8wDQYJ
KoZIhvcNAQEBBQADgY0AMIGJAoGBAMSmPFVzVftOucqZWh5owHUEcJ3f6f+jHuy9zfVb8hp2
vX8MOmHyv1HOAdTlUAow1wJjWiyJFXCO3cnwK4Vaqj9xVsuvPAsH5/EfkTYkKhPPK9Xzgnc9
A74r/rsYPge/QIACZNenprufZdHFKlSFD0gEf6e20TxhBEAeZBlyYLf7AgMBAAGjgZQwgZEw
EgYDVR0TAQH/BAgwBgEB/wIBADBDBgNVHR8EPDA6MDigNqA0hjJodHRwOi8vY3JsLnRoYXd0
ZS5jb20vVGhhd3RlUGVyc29uYWxGcmVlbWFpbENBLmNybDALBgNVHQ8EBAMCAQYwKQYDVR0R
BCIwIKQeMBwxGjAYBgNVBAMTEVByaXZhdGVMYWJlbDItMTM4MA0GCSqGSIb3DQEBBQUAA4GB
AEiM0VCD6gsuzA2jZqxnD3+vrL7CF6FDlpSdf0whuPg2H6otnzYvwPQcUCCTcDz9reFhYsPZ
Ohl+hLGZGwDFGguCdJ4lUJRix9sncVcljd2pnDmOjCBPZV+V2vf3h9bGCE6u9uo05RAaWzVN
d+NWIXiC3CEZNd4ksdMdRv9dX2VPMYIDOzCCAzcCAQEwaTBiMQswCQYDVQQGEwJaQTElMCMG
A1UEChMcVGhhd3RlIENvbnN1bHRpbmcgKFB0eSkgTHRkLjEsMCoGA1UEAxMjVGhhd3RlIFBl
cnNvbmFsIEZyZWVtYWlsIElzc3VpbmcgQ0ECAw7NrTAJBgUrDgMCGgUAoIIBpzAYBgkqhkiG
9w0BCQMxCwYJKoZIhvcNAQcBMBwGCSqGSIb3DQEJBTEPFw0wNjAyMjQyMzE2MzlaMCMGCSqG
SIb3DQEJBDEWBBRocPmBlGBLpWsTgyFCyxi1qocFQjBSBgkqhkiG9w0BCQ8xRTBDMAoGCCqG
SIb3DQMHMA4GCCqGSIb3DQMCAgIAgDANBggqhkiG9w0DAgIBQDAHBgUrDgMCBzANBggqhkiG
9w0DAgIBKDB4BgkrBgEEAYI3EAQxazBpMGIxCzAJBgNVBAYTAlpBMSUwIwYDVQQKExxUaGF3
dGUgQ29uc3VsdGluZyAoUHR5KSBMdGQuMSwwKgYDVQQDEyNUaGF3dGUgUGVyc29uYWwgRnJl
ZW1haWwgSXNzdWluZyBDQQIDDs2tMHoGCyqGSIb3DQEJEAILMWugaTBiMQswCQYDVQQGEwJa
QTElMCMGA1UEChMcVGhhd3RlIENvbnN1bHRpbmcgKFB0eSkgTHRkLjEsMCoGA1UEAxMjVGhh
d3RlIFBlcnNvbmFsIEZyZWVtYWlsIElzc3VpbmcgQ0ECAw7NrTANBgkqhkiG9w0BAQEFAASC
AQBGulZbvHVlBuAonc6jowXWIj8WgBVP0avSvo/ZSFuNVjeNUJc4U3wXZe70/fVEaovHYVt5
9bVU3B4YwD39Jxrb79Nqy0lADILq3xFElZVKfgwt1apXTFROztfsPgyOJxvKFV/d9kX3oz8/
OFLaidwGmOxmR6Ls61cAssINo5V3oXipIA3O6EXl60D6fC3iCvb7uwazkneuAKf/TGqs3eQ4
65rmLfvV4NBk5/1SYmMixcuVwEA3RKXWj6/C8LggvzEfch9kVhVLKvOrneEAMsaGgu6t/VPR
WRwb3aOFb00HYVLZhz6R2NBIej7drtoROO9Hs3E1yOn0oNBwTfo1HXsiAAAAAAAA
--------------ms080403080000090106070401--