Adding a Flexible GetSize RPC Variant to the AFS-3 Volume Service
draft-deason-afs3-getsizev2-01

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 Service. While an RPC already exists for this purpose (GetSize), this document proposes a more flexible mechanism that is able to more accurately determine the size of a volume dump in a greater number of cases.

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 September 02, 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. Conventions Used in this Document
• 3. Error Codes
• 4. RPC Interface
• 4.1. GetSizeV2
• 4.2. GetSizeV2 Flags
• 5. Extant RPC Interface
• 5.1. DumpV2
• 5.2. GetSize
• 5.3. DumpV2 Flags
• 6. Security Considerations
• 7. IANA Considerations
• 8. AFS-3 Registry Considerations
• 9. Acknowledgments
• 10. References
• 10.1. Normative References
• 10.2. Informative 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.

To allow computation of the size of volumes returned by the Dump RPC, a GetSize RPC was provided. 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. This document describes a new RPC, GetSizeV2, to fill this gap, to allow computation of the sizes of volume dumps generated by DumpV2.

2. Conventions Used in this Document

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

3. Error Codes

The existing VOLSERBAD_ACCESS, VOLSERTRELE_ERROR, and ENOENT error codes are used by the new RPC defined within this document. The meaning and value of these error codes can be found in [AFS3-VVL], with the exception of ENOENT's value. ENOENT is defined to have the value 2.

4. RPC Interface

One new RPC code is defined for the Volume Service: GetSizeV2. Additionally, a new namespace for GetSizeV2 flags is defined, and one flag in that namespace is defined.

4.1. GetSizeV2

This behaves exactly the same way as the existing GetSize RPC (Section 5.2), except for the addition of the flags argument, which behaves similarly to the flags argument of the existing DumpV2 RPC (Section 5.3).

    GetSizeV2(IN afs_int32 fromTrans, IN afs_int32 fromDate,
              IN afs_int32 flags, OUT struct volintSize *size) = XXX;

Input arguments:

fromTrans

A transaction ID as returned by the RPC TransCreate.

fromDate

The meaning and format of this argument is the same as the fromDate argument described in Section 5.1. Since this is represented as a signed 32-bit integer, problems may occur if dates beyond 2038 are specified. A future protocol revision will improve the date representation in AFSVol RPCs to address this problem.

flags

Zero or more flags combined via a bitwise OR operation. The available flags are described below in Section 4.2.

Output arguments:

size

The size of the dump, represented in bytes.

The call is aborted with an error for all of the same conditions where Dump aborts with an error as described in [AFS3-VVL], with the appropriate error code.

4.2. GetSizeV2 Flags

The intention of the GetSizeV2 RPC is to provide an extension to the GetSize RPC, similar to how DumpV2 provided an analogous extension to Dump. As such, the only defined GetSizeV2 flag corresponds to the single existing DumpV2 flag, though there is no requirement that every GetSizeV2 flag have a DumpV2 equivalent, or vice versa.

VOLGETSIZEV2_OMITDIRS = 1

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 (Section 5.3) was set. Such a dump does not include directory information for directories that have not changed since the specified fromDate.

5. Extant RPC Interface

The newly-defined RPC GetSizeV2 has very similar behavior to the RPCs DumpV2 and GetSize. While these RPCs already exist and are in use, there is no existing document describing their behavior in significant detail. Their behavior is briefly described here, so the role of GetSizeV2 may be better understood.

5.1. DumpV2

The DumpV2 RPC generates a canonical dump of the contents of a volume associated with a volume transaction. It is identical to the Dump RPC ([AFS3-VVL]), except for the addition of the flags parameter.

    DumpV2(IN afs_int32 fromTrans, IN afs_int32 fromDate,
           IN afs_int32 flags) split = 65538;

Input arguments:

fromTrans

A transaction ID as returned by the RPC TransCreate.

fromDate

If 0, the generated volume dump will be a "full dump", and will contain all data in the volume. Otherise, this represents a calendar date, represented as the number of seconds since the Unix Epoch. The generated dump will then only contain files that have been modified on or after the specified calendar date.

flags

Zero or more flags combined via a bitwise OR operation. The available flags are described below in Section 5.3.

As with Dump, the generated volume dump for DumpV2 appears in the Rx stream for the split call ([AFS3-RX]) if there are no errors. The call is aborted with an error for all of the same conditions where Dump aborts with an error as described in [AFS3-VVL], with the appropriate error code.

5.2. GetSize

The GetSize RPC calculates what the size of a volume dump obtained from calling Dump ([AFS3-VVL]) would be. This allows dump sizes to be calculated without needing to generate and transfer the entire volume dump.

    struct volintSize {
        afs_uint64 dump_size;
    };

    GetSize(IN afs_int32 fromTrans, IN afs_int32 fromDate,
            OUT struct volintSize *size) = 65537;

Input arguments:

fromTrans

A transaction ID as returned by the RPC TransCreate.

fromDate

The meaning and format of this argument is the same as the fromDate argument described in Section 5.1.

Output arguments:

size

The size of the dump, represented in bytes.

The call is aborted with an error for all of the same conditions where Dump aborts with an error as described in [AFS3-VVL], with the appropriate error code.

5.3. DumpV2 Flags

The DumpV2 RPC allows the caller to optionally specify a set of 0 or more flags which slightly alter the behavior of the DumpV2 call. Only one such flag is currently defined:

VOLDUMPV2_OMITDIRS = 1

Normally, an incremental volume dump generated by Dump or DumpV2 includes the data for all directories in the volume, even if nothing in that directory has changed. This is to allow data in an incremental dump to still be easily accessible even if the incremental dump is the only dump available. If the flag VOLDUMPV2_OMITDIRS is specified, the generated volume dump will only contain directory data if the directory was modified at or after the specified fromDate. This reduces the size of the dump, but can make it more difficult to retrieve data from the dump if the original full volume dump is lost.

6. Security Considerations

The results of the GetSize and GetSizeV2 RPCs are not normally considered sensitive information, though they may be computationally intensive to calculate. As such, current AFS-3 implementations typically use some per-server superuser list (such as the AFS-3 Basic OverSeer UserList) to control access to the GetSize RPC to reduce potential Denial of Service attack vectors. While this practice is OPTIONAL for implementations and subject to site-specific policies, any access control restrictions that apply to the GetSize RPC SHOULD also apply to GetSizeV2 (and vice versa) for consistency.

7. IANA Considerations

This document makes no request of the IANA.

8. AFS-3 Registry Considerations

This document requires the registration of one RPC code point for the AFSVol GetSizeV2 RPC detailed above in Section 4 by the the AFS-3 Assigned Numbers Registry.

This document also requests that the AFS-3 Assigned Numbers Registry assumes control over the GetSizeV2 flags namespace. This document defines one flag in this namespace, AFSVOLGETSIZEV2_OMITDIRS, detailed above in Section 4.2, with the value of 1.

9. Acknowledgments

The author thanks David Boyes and Jeffrey T. Hutzelman for their discussion on Rx return codes, and Derrick Brashear for his work and feedback on representing calendar dates in AFSVol.

10. References

10.1. Normative References

10.2. Informative References

Author's Address