N/A A. Deason Internet-Draft Sine Nomine Intended status: Informational February 2, 2011 Expires: August 6, 2011 Adding a Flexible GetSize RPC Variant to the AFS-3 Volume Service draft-deason-afs3-getsizev2-00 Abstract This document describes an additional RX remote procedure call that may be used to obtain the size of an AFS-3 volume dump from an AFS-3 Volume Server service with greater flexibility and granularity. Internet Draft Comments Comments regarding this draft are solicited. Please include the AFS-3 protocol standardization mailing list (afs3-standardization@openafs.org) as a recipient of any comments Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on August 6, 2011. Copyright Notice Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect Deason Expires August 6, 2011 [Page 1]
Internet-Draft AFS-3 AFSVol Flexible GetSize February 2011 to this document. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. RPC Interface . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.1. GetSizeV2 . . . . . . . . . . . . . . . . . . . . . . . . . 3 3.2. GetSizeV2 Flags . . . . . . . . . . . . . . . . . . . . . . 4 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 4 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 6. AFS-3 Registry Considerations . . . . . . . . . . . . . . . . . 5 7. Informative References . . . . . . . . . . . . . . . . . . . . 5 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 5 Deason Expires August 6, 2011 [Page 2]
Internet-Draft AFS-3 AFSVol Flexible GetSize February 2011 1. Introduction AFS-3 provides a service (the "Volume Service") [AFS3-VVL] which allows administrators to examine and manage AFS-3 volumes via several RX remote procedure calls in the AFSVol package. One of these RPCs, Dump, can be used to obtain a dump of an AFS-3 volume that can be stored on disk, usually for backup or archival purposes. Another RPC, DumpV2, was later added to allow the caller to make slight modifications to what data is contained in the dump by way of specifying certain flags in an additional argument. Another RPC, GetSize, can be used to obtain what the size of a dump obtained with Dump would be without needing to actually retrieve the full dump. However, no analogous RPC exists to determine what the size of a volume dump obtained via DumpV2 would be if any flags were specified in the DumpV2 call. 2. Error Codes The existing VOLSERBAD_ACCESS, VOLSERTRELE_ERROR, and ENOENT error codes are used by the new RPC defined within this document. 3. RPC Interface One new RPC is defined for the Volume Service: GetSizeV2. Additionally, a new namespace for GetSizeV2 flags is defined, and one flag in that namespace is defined. 3.1. GetSizeV2 This behaves exactly the same way as the existing GetSize RPC, except for the addition of the flags argument, which behaves similarly to the flags argument of the existing DumpV2 RPC. GetSizeV2(IN afs_int32 fromTrans, IN afs_int32 fromDate, IN afs_int32 flags, OUT struct volintSize *size) = XXX; The fromTrans parameter is a transaction ID as returned by the RPC TransCreate. The size calculated will be the size of an incremental dump containing volume changes made after the specified calendar time fromDate, specified as the number of seconds since the Unix Epoch. If the specified fromDate is 0, the size for a full volume dump will be reported. The flags parameter is zero or more flags combined via a bitwise OR operation. The available flags are described below in Section 3.2. Deason Expires August 6, 2011 [Page 3]
Internet-Draft AFS-3 AFSVol Flexible GetSize February 2011 The calculated dump size will be returned in the size parameter, represented in bytes. On success, the call returns 0. If the calling user does not have sufficient permission, VOLSERBAD_ACCESS is returned. If the specified transaction does not exist, ENOENT is returned. If there is an error releasing the volume transaction, VOLSERTRELE_ERROR is returned. 3.2. GetSizeV2 Flags The defined flags for GetSizeV2 are analogous to the flags in DumpV2, although all future flags defined for GetSizeV2 need not have equivalents in DumpV2 and vice versa. As such, since there is only one flag currently defined for DumpV2 (VOLDUMPV2_OMITDIRS), there is only one flag defined for GetSizeV2: VOLGETSIZEV2_OMITDIRS = XXX This is the GetSizeV2 analogue of the DumpV2 flag VOLDUMPV2_OMITDIRS. If this flag is set, the volume dump size will be calculated for a dump generated by a DumpV2 call where the flag VOLDUMPV2_OMITDIRS was set. Such a dump does not include directory information for the parent directories of any modified directory entries, if the modification time for the parent directories are earlier than the specified fromDate. 4. Security Considerations Current AFS-3 implementations only allow users listed in the server's AFS-3 Basic OverSeer's UserList to issue Dump, DumpV2, and GetSize RPCs successfully. It is recommended that implementations also only allow such users to issue the GetSizeV2 RPC for consistency and to reduce potential Denial of Service attack vectors from unauthenticated clients. Additionally, while the size of a volume is not sensitive (and may be obtained from other RPCs from an unauthenticated user, such as XListVolumes), information on when a volume's contents have changed might be considered sensitive under some circumstances. And since the GetSize and GetSizeV2 RPCs are generally only useful to members of the UserList, it makes little sense to allow any other users to call them. Deason Expires August 6, 2011 [Page 4]
Internet-Draft AFS-3 AFSVol Flexible GetSize February 2011 5. IANA Considerations This document makes no request of the IANA. 6. AFS-3 Registry Considerations This document requires the registration of one code point for the AFSVol GetSizeV2 RPC detailed above. This document also requests that the AFS-3 Registrar assumes control over the GetSizeV2 flags namespace. This document requires the registration of one flag in this namespace, AFSVOLGETSIZEV2_OMITDIRS, detailed above. 7. Informative References [AFS3-VVL] Zayas, E., "AFS-3 Programmer's Reference: Volume Server/ Volume Location Server Interface", Transarc Corp. Tech. Rep. FS-00-D165, August 1991. Author's Address Andrew Deason Sine Nomine Associates 43596 Blacksmith Square Ashburn, Virginia 20147-4606 USA Phone: +1 703 723 6673 Email: adeason@sinenomine.net Deason Expires August 6, 2011 [Page 5]