N/A A. Deason
Internet-Draft Sine Nomine
Intended status: Informational March 30, 2011
Expires: October 1, 2011
Adding a Flexible GetSize RPC Variant to the AFS-3 Volume Service
draft-deason-afs3-getsizev2-03
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
(AFSVolGetSize), 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 October 1, 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
Deason Expires October 1, 2011 [Page 1]
Internet-Draft AFS-3 AFSVol Flexible GetSize March 2011
(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 . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions Used in this Document . . . . . . . . . . . . . . . 3
3. Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Extant RPC Interface . . . . . . . . . . . . . . . . . . . . . 3
4.1. AFSVolDumpV2 . . . . . . . . . . . . . . . . . . . . . . . 3
4.2. AFSVolGetSize . . . . . . . . . . . . . . . . . . . . . . . 4
4.3. AFSVolDumpV2 Flags . . . . . . . . . . . . . . . . . . . . 5
5. RPC Interface . . . . . . . . . . . . . . . . . . . . . . . . . 5
5.1. AFSVolGetSizeV2 . . . . . . . . . . . . . . . . . . . . . . 6
5.2. AFSVolGetSizeV2 Flags . . . . . . . . . . . . . . . . . . . 6
6. Security Considerations . . . . . . . . . . . . . . . . . . . . 7
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7
8. AFS-3 Registry Considerations . . . . . . . . . . . . . . . . . 7
8.1. RPC code points . . . . . . . . . . . . . . . . . . . . . . 7
8.2. AFSVolGetSizeV2 flags namespace . . . . . . . . . . . . . . 7
8.3. AFSVolDumpV2 flags namespace . . . . . . . . . . . . . . . 8
9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . 8
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8
10.1. Normative References . . . . . . . . . . . . . . . . . . . 8
10.2. Informative References . . . . . . . . . . . . . . . . . . 8
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 8
Deason Expires October 1, 2011 [Page 2]
Internet-Draft AFS-3 AFSVol Flexible GetSize March 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 (RPCs) in the AFSVol package. One of these
RPCs, AFSVolDump, 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, AFSVolDumpV2, 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
AFSVolDump RPC, an AFSVolGetSize RPC was provided. However, no
analogous RPC exists to determine what the size of a volume dump
obtained via AFSVolDumpV2 would be if any flags were specified in the
AFSVolDumpV2 call. This document describes a new RPC,
AFSVolGetSizeV2, to fill this gap, to allow computation of the sizes
of volume dumps generated by AFSVolDumpV2.
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. Extant RPC Interface
The newly-defined RPC AFSVolGetSizeV2 has very similar behavior to
the RPCs AFSVolDumpV2 and AFSVolGetSize. 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 AFSVolGetSizeV2 may be better understood.
4.1. AFSVolDumpV2
The AFSVolDumpV2 RPC generates a canonical dump of the contents of a
volume associated with a volume transaction. It is identical to the
Deason Expires October 1, 2011 [Page 3]
Internet-Draft AFS-3 AFSVol Flexible GetSize March 2011
AFSVolDump RPC [AFS3-VVL], except for the addition of the flags
parameter.
AFSVolDumpV2(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 AFSVolTransCreate.
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 4.3.
As with AFSVolDump, the generated volume dump for AFSVolDumpV2
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 AFSVolDump aborts with an error as described in
[AFS3-VVL], with the appropriate error code.
4.2. AFSVolGetSize
The AFSVolGetSize RPC calculates what the size of a volume dump
obtained from calling AFSVolDump [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;
};
AFSVolGetSize(IN afs_int32 fromTrans, IN afs_int32 fromDate,
OUT struct volintSize *size) = 65537;
Input arguments:
Deason Expires October 1, 2011 [Page 4]
Internet-Draft AFS-3 AFSVol Flexible GetSize March 2011
fromTrans
A transaction ID as returned by the RPC AFSVolTransCreate.
fromDate
The meaning and format of this argument is the same as the
fromDate argument described in Section 4.1.
Output arguments:
size
The size of the dump, represented in octets.
The call is aborted with an error for all of the same conditions
where AFSVolDump aborts with an error as described in [AFS3-VVL],
with the appropriate error code.
4.3. AFSVolDumpV2 Flags
The AFSVolDumpV2 RPC allows the caller to optionally specify a set of
0 or more flags which slightly alter the behavior of the AFSVolDumpV2
call. Only one such flag is currently defined:
VOLDUMPV2_OMITDIRS = 1
Normally, an incremental volume dump generated by AFSVolDump or
AFSVolDumpV2 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.
5. RPC Interface
One new RPC code is defined for the Volume Service: AFSVolGetSizeV2.
Additionally, a new namespace for AFSVolGetSizeV2 flags is defined,
and one flag in that namespace is defined.
Deason Expires October 1, 2011 [Page 5]
Internet-Draft AFS-3 AFSVol Flexible GetSize March 2011
5.1. AFSVolGetSizeV2
The AFSVolGetSizeV2 RPC behaves exactly the same way as the existing
AFSVolGetSize RPC (Section 4.2), except for the addition of the flags
argument, which behaves similarly to the flags argument of the
existing AFSVolDumpV2 RPC (Section 4.3).
AFSVolGetSizeV2(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 AFSVolTransCreate.
fromDate
The meaning and format of this argument is the same as the
fromDate argument described in Section 4.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 5.2.
Output arguments:
size
The size of the dump, represented in octets.
The call is aborted with an error for all of the same conditions
where AFSVolDump aborts with an error as described in [AFS3-VVL],
with the appropriate error code.
5.2. AFSVolGetSizeV2 Flags
The intention of the AFSVolGetSizeV2 RPC is to provide an extension
to the AFSVolGetSize RPC, similar to how AFSVolDumpV2 provided an
analogous extension to AFSVolDump. As such, the only defined
AFSVolGetSizeV2 flag corresponds to the single existing AFSVolDumpV2
flag, though there is no requirement that every AFSVolGetSizeV2 flag
Deason Expires October 1, 2011 [Page 6]
Internet-Draft AFS-3 AFSVol Flexible GetSize March 2011
have an AFSVolDumpV2 equivalent, or vice versa.
VOLGETSIZEV2_OMITDIRS = 1
This is the AFSVolGetSizeV2 analogue of the AFSVolDumpV2 flag
VOLDUMPV2_OMITDIRS. If this flag is set, the volume dump size
will be calculated for a dump generated by an AFSVolDumpV2 call
where the flag VOLDUMPV2_OMITDIRS (Section 4.3) was set. Such a
dump does not include directory information for directories that
have not changed since the specified fromDate.
6. Security Considerations
The results of the AFSVolGetSize and AFSVolGetSizeV2 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 OpenAFS Basic OverSeer UserList) to control access to the
AFSVolGetSize 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 AFSVolGetSize RPC SHOULD also apply to
AFSVolGetSizeV2 (and vice versa) for consistency.
7. IANA Considerations
This document makes no request of the IANA.
8. AFS-3 Registry Considerations
8.1. RPC code points
This document requires the registration of one RPC code point in the
AFSVol Rx package for the AFSVolGetSizeV2 RPC detailed above in
Section 5.1.
8.2. AFSVolGetSizeV2 flags namespace
This document requests that the AFS-3 Assigned Numbers Registry
assumes control over the AFSVolGetSizeV2 flags namespace.
AFSVolGetSizeV2 flags have values from 0x1 to 0x80000000, and must be
a power of two. This document suggests that the AFS-3 Assigned
Numbers Registry assume control of allocating flags in the range
0x00000001-0x00800000, and that flags in the range 0x01000000-
0x80000000 are left to Private Use as defined by [RFC5226].
Deason Expires October 1, 2011 [Page 7]
Internet-Draft AFS-3 AFSVol Flexible GetSize March 2011
This document defines one initial assignment in the AFSVolGetSizeV2
flags namespace. VOLGETSIZEV2_OMITDIRS, detailed above in
Section 5.2, is assigned the value of 1.
8.3. AFSVolDumpV2 flags namespace
This document requests that the AFS-3 Assigned Numbers Registry
assumes control over the AFSVolDumpV2 flags namespace. There is only
one such flag currently in use: VOLDUMPV2_OMITDIRS with the value of
1, as described in Section 4.3. This document suggests an allocation
policy for AFSVolDumpV2 flags identical to the allocation policy
described in Section 8.2.
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
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
10.2. Informative References
[AFS3-RX] Zayas, E., "AFS-3 Programmer's Reference: Specification
for the Rx Remote Procedure Call Facility", Transarc Corp.
Tech. Rep. FS-00-D164, August 1991.
[AFS3-VVL]
Zayas, E., "AFS-3 Programmer's Reference: Volume Server/
Volume Location Server Interface", Transarc Corp. Tech.
Rep. FS-00-D165, August 1991.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
Deason Expires October 1, 2011 [Page 8]
Internet-Draft AFS-3 AFSVol Flexible GetSize March 2011
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 October 1, 2011 [Page 9]