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 06, 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 to this document.

Table of Contents

• 1. Introduction
• 2. Error Codes
• 3. RPC Interface
• 3.1. GetSizeV2
• 3.2. GetSizeV2 Flags
• 4. Security Considerations
• 5. IANA Considerations
• 6. AFS-3 Registry Considerations
• 7. References
• Author's Address

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

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

Author's Address