AFSVol Tag-Length-Value Remote Procedure Call Extensions
draft-tkeiser-afs3-volser-tlv-00

Abstract

AFS-3 heavily leverages Remote Procedure Calls (RPCs). This proposal adds a new mechanism to better manage the addition of new, enhancement-specific RPCs through the use of both capability bits via the GetCapabilities RPC, and via standardization of backwards-compatibility behaviors for enhancement-specific RPCs. These goals are accomplished through standardization of Tag-Length-Value (TLV) get/set/enumerate RPCs with value payloads encoded using an XDR discriminated union. The XDR union decode problem is circumvented by specifying an opaque default leg. Tags are allocated for existing volume and transaction metadata, and implementation-private tags are allocated for metadata related to the OpenAFS Demand Attach File Server.

Status of this Memo

This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

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

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on May 21, 2010.

Copyright Notice

Copyright (c) 2009 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. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the BSD License.

Table of Contents

1.  Introduction
    1.1.  Requirements Language
2.  GetCapabilities RPC
    2.1.  Description
3.  Backward Compatibility
    3.1.  GetCapabilities
        3.1.1.  AFSVol
        3.1.2.  Capability Bit Allocations
4.  TLV Interface
    4.1.  Encoding
    4.2.  Interface
        4.2.1.  Qualifiers
        4.2.2.  Tag Introspection
        4.2.3.  TLV Get
        4.2.4.  TLV Streaming Get
            4.2.4.1.  Split call stream encoding
        4.2.5.  TLV Set
            4.2.5.1.  Call preprocessing
            4.2.5.2.  Call processing
5.  Mapping of existing metadata onto TLV namespace
    5.1.  volintXInfo
    5.2.  transDebugInfo
    5.3.  Additional de facto-standardized fields
6.  Extended volume state exportation
    6.1.  Mapped volume states
    6.2.  Mapped process types
    6.3.  TLV tuples
7.  Acknowledgements
8.  IANA Considerations
9.  GCO Registrar Considerations
    9.1.  Namespace allocations
    9.2.  Assigned numbers allocations
        9.2.1.  VICED capability bits
        9.2.2.  AFSVol capability bits
        9.2.3.  AFS-3 TLV payload types
        9.2.4.  AFSVol TLV tags
        9.2.5.  VOLS error table
        9.2.6.  AFSVol mapped volume names
        9.2.7.  AFS-3 program types
10.  Security Considerations
11.  References
    11.1.  Normative References
    11.2.  Informative References
Appendix A.  XDR Grammar for FS-CM Capabilities Mechanism
§  Authors' Addresses

1.  Introduction

The AFS protocol stores data in volumes on fileservers. Status information for volumes is accessible via various AFSVol RPCs. Adding or modifying fields currently requires creation of new RPCs. As these new RPCs differ only slightly from existing ones, a scalable approach to RPC modification is needed. This is accomplished through the creation of Tag-Length-Value (TLV) RPCs for the existing RPCs; for example, AFSVolGetOneVolumeTLV is the Tag-Length-Value equivalent to the AFS-3 AFSVolListOneVolume RPC.

As a concrete example of Tag-Length-Value RPCs for volume status information, the Demand Attach File Server creates new states for volumes. Several new tags are allocated by this memo to export raw and canonical state information which DAFS can provide, but which legacy AFS-3 is incapable of communicating.

1.1.  Requirements Language

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 RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

2.  GetCapabilities RPC

2.1.  Description

The AFS-3 specifications ([AFS3‑FSCM] (Zayas, E., “AFS-3 Programmer's Reference: File Server/Cache Manager Interface,” August 1991.), [AFS3‑VVL] (Zayas, E., “AFS-3 Programmer's Reference: Volume Server/Volume Location Server Interface,” August 1991.)) describe various AFS RPCs. As new extensions and modifications to AFS occur, a mechanism needs to be in place so that growth of RPCs is done in a manageable fashion. Of particular concern is a proliferation of modified versions of RPCs that differ from each other in minor ways; examples are:

• RXAFSCB_InitCallBackState, RXAFSCB_InitCallBackState2, and RXAFSCB_InitCallBackState3
• RXAFS_FetchData versus RXAFS_FetchData64

Instead of continuing the practice of adding a version number, width of value, or other identifier to the end of the RPC name, this document specifies that RPC extensions, where necessary, be created with a "TLV" suffix denoting "Tag-Length-Value", a tag-value identifier be obtained from the Registrar, and that interoperability done according to the following section.

3.  Backward Compatibility

Services providing extended Tag-Length-Value RPCs MUST provide backwards compatible interfaces to both legacy clients and servers. Additionally, interoperability between TLV versions must also be specified if they do not comply with the following requirements:

1. AFS-3 TLV servers replying to AFS-3 clients MUST provide the identical response to an AFS-3 server.
2. AFS-3 TLV clients communicating with AFS-3 servers MUST fall back to using non-TLV RPCs.
3. AFS-3 TLV clients to AFS-3 TLV servers:

   A.

   Where capabilities match or the server can provide capabilities including those which the client requests, the server MUST reply with exactly the capabilities requested.

   B.

   Where the client requests capabilities that the server does not provide it MUST either return an 'unknown tag' error code, or (OPTIONAL) fall back to an AFS-3 response.

3.1.  GetCapabilities

All AFS-3 Rx services with Tag-Length-Value RPCs MUST implement a GetCapabilities RPC analogous to that done for the FS-CM interface.

3.1.1.  AFSVol

This memo introduces a capabilities namespace, and GetCapabilities interface to the AFSVol service. For AFSVol the GetCapabilities interface will be be identical to the afsint interface, and will be defined as follows:

proc GetCapabilities(
    OUT Capabilities * capabilities
) = XXX;

The "Capabilities" type is defined by the existing afsint interface, which is included here for reference:

const AFSCAPABILITIESMAX = 192;

typedef afs_int32 Capabilities<AFSCAPABILITIESMAX>;

3.1.2.  Capability Bit Allocations

Three new capability bit allocations will need to be processed by the Grand Central Registrar:

VICED_CAPABILITY_DAFS

Announce that this file server supports the OpenAFS Demand Attach File Server version 1 semantics

AFSVOL_CAPABILITY_DAFS

Announce that this volume server supports the OpenAFS Demand Attach File Server version 1 semantics

AFSVOL_CAPABILITY_TLV

Announce that this volume server supports the Tag-Length-Value RPC

4.  TLV Interface

A new suite of RPCs will be standardized to get/set tag-length-value tuples, and to enumerate supported tags. The tag namespace will be controlled by the Grand Central Registrar as an assigned numbers namespace.

4.1.  Encoding

The TLV data will be encoded using the following XDR specification:

/* registrar-controlled tag namespace */

enum AFSVol_TLV_tag {
    ...
};

const AFSINT_TLV_TAG_MAX = 1024;         /* upper-bound on number of
                                          * TLV tuples per RPC */
const AFSINT_TLV_OPAQUE_MAX = 262144;    /* upper-bound on size of
                                          * value payload */

enum afsint_TLV_type {
    AFSINT_TLV_TYPE_NULL     = 0,
    AFSINT_TLV_TYPE_TRUE     = 1,
    AFSINT_TLV_TYPE_FALSE    = 2,
    AFSINT_TLV_TYPE_UINT64   = 3,
    AFSINT_TLV_TYPE_UUID     = 4,
    AFSINT_TLV_TYPE_STRING   = 5,
    AFSINT_TLV_TYPE_OPAQUE   = 6
};

union afsint_TLV_value switch(afsint_TLV_type type) {
 case AFSINT_TLV_TYPE_NULL:
 case AFSINT_TLV_TYPE_TRUE:
 case AFSINT_TLV_TYPE_FALSE:
  void;

 case AFSINT_TLV_TYPE_UINT64:
    afs_uint64 u_64;

 case AFSINT_TLV_TYPE_UUID:
    afsUUID u_uuid;

 case AFSINT_TLV_TYPE_STRING:
    string u_string<AFSINT_TLV_OPAQUE_MAX>;

 case AFSINT_TLV_TYPE_OPAQUE:
 default:
    opaque u_opaque<AFSINT_TLV_OPAQUE_MAX>;
};

const AFSINT_TLV_FLAG_UNSUPPORTED = 0x1;
const AFSINT_TLV_FLAG_READ_ERROR = 0x2;
const AFSINT_TLV_FLAG_CRITICAL = 0x4;

struct afsint_TLV {
    afs_uint32 tlv_tag;
    afs_uint32 tlv_flags;
    afsint_TLV_value tlv_value;
};

TLV XDR specification

In order to solve the XDR discriminated union decoding problem, all future afsint_TLV_type allocations will map to opaque. All implementations MUST support all arms in the afsint_TLV_value XDR union, as defined above.

It is RECOMMENDED that future protocol augmentations requiring the transmission of new data types request allocation of a new standards-track payload type code. Allocation of a type code should coincide with standardization of the payload encoding associated with the type code allocation. However, in limited circumstances where:

1. it is known a priori that there will never be any encoding ambiguity, and
2. the cost of type code allocation and encoding standardization are deemed too high

use of the type code AFSINT_TLV_TYPE_OPAQUE may be permissible.

4.2.  Interface

4.2.1.  Qualifiers

In some cases the value associated with a tag will be large, structured data. A qualifier is a tag-specific parameter which allows a caller to address a subset of the value stored in a tag. For TLV get interfaces, specifying a qualifer can reduce the amount of data sent over the wire. For TLV set interfaces, specifying a qualifier permits a client to modify a subset of a structured value without endangering cache coherence. Qualifiers are marshalled over the wire as type afsint_TLV_value. Unless otherwise noted, it should be assumed that a tag only supports the null qualifier (XDR union discriminator set to AFSINT_TLV_TYPE_NULL). The null qualifier always references the entire value for a given tag.

4.2.2.  Tag Introspection

The Rx procedure specification for the tag support RPC will be as follows:

proc GetVolumeTLVTags(
    IN AFSVol_TLV_tag offset,
    OUT AFSVol_TLV_tag * tags<AFSINT_TLV_TAG_MAX>
) = XXX;

The call parameters are defined as follows:

offset

The offset IN parameter specifies the numeric offset of the first tag to return. A value of zero indicates that the client wants to start the enumeration at the beginning of the tag list.

tags

The tags OUT parameter contains a sorted list of supported tags, beginning with the first supported tag greater than or equal to the offset IN parameter.

4.2.3.  TLV Get

The Rx procedure specification for the TLV get interface will be as follows:

struct AFSVol_TLV_query {
    AFSVol_TLV_tag tq_tag;
    afsint_TLV_value tq_qualifier;
};

proc GetOneVolumeTLV(
    IN afs_uint32 partId,
    IN afs_uint64 volId,
    IN AFSVol_TLV_query queries<AFSINT_TLV_TAG_MAX>,
    OUT afsint_TLV * tuples<AFSINT_TLV_TAG_MAX>
) = XXX;

The call parameters are defined as follows:

partId

The partId IN parameter specifies the disk partition on which the volume is located.

volId

The volId IN parameter specifies the volume for which TLV tuples are being requested.

queries

The queries IN parameter specifies an optional list of tags for which TLV tuples are desired. If this parameter is zero-length, then the server will return up to AFSINT_TLV_TAG_MAX TLV tuples. If an unknown tag identifier is passed in the tags parameter, then the server will return a tuple with the AFSINT_TLV_FLAG_UNSUPPORTED bit asserted in afsint_TLV.tlv_flags, and the tlv type set to AFSINT_TLV_TYPE_NULL. Similarly, if the server is unable to retrieve the value for a supported tag, then a tuple will be returned with AFSINT_TLV_FLAG_READ_ERROR set in the afsint_TLV.tlv_flags field, and the tlv type set to AFSINT_TLV_TYPE_NULL. The AFSVol_TLV_query.tq_qualifier field contains optional tag-specific qualifiers which would allow the implementation to return a subset of the data for a specific tag.

tuples

The tuples OUT parameter contains up to AFSINT_TLV_TAG_MAX TLV tuples for this volume.

4.2.4.  TLV Streaming Get

This call is similar to the call described in the previous section, with the exception that TLV tuples will be returned for multiple volumes at once using an Rx split call interface. The Rx procedure specification is as follows:

const AFSVOL_BULK_GETVOLUME_MAX = 1024;

proc GetVolumesTLV(
    IN afs_uint32 partIds<AFSVOL_BULK_GETVOLUME_MAX>,
    IN afs_uint64 volIds<AFSVOL_BULK_GETVOLUME_MAX>,
    IN AFSVol_TLV_query queries<AFSINT_TLV_TAG_MAX>
) split = XXX;

The call parameters are defined as follows:

partIds

The partIds IN parameter specifies as list of vice partitions. If this list is zero-length, then TLV information is requested for all volumes on all vice partitions. If this list is non-zero length, then TLV information is requested only for volumes on specific vice partitions.

volIds

The volIds IN parameter specifies a list of volume IDs. If this list is zero-length, then TLV information is requested for all volumes on the vice partitions specified in partIds.
If the volIds array is non-zero length, then its length MUST match the length of the partIds array. In this case, each matching index in the partIds and volIds arrays together form a tuple which uniquely addresses a volume on a given vice partition.

queries

The queries IN parameter specifies an optional list of tags for which TLV tuples are desired. If this parameter is zero-length, then the server will return up to AFSINT_TLV_TAG_MAX TLV tuples. If an unknown tag identifier is passed in the tags parameter, then the server will return a tuple with the AFSINT_TLV_FLAG_UNSUPPORTED bit asserted in afsint_TLV.tlv_flags, and the tlv type set to AFSINT_TLV_TYPE_NULL. Similarly, if the server is unable to retrieve the value for a supported tag, then a tuple will be returned with AFSINT_TLV_FLAG_READ_ERROR set in the afsint_TLV.tlv_flags field, and the tlv type set to AFSINT_TLV_TYPE_NULL. The AFSVol_TLV_query.tq_qualifier field contains optional tag-specific qualifiers which would allow the implementation to return a subset of the data for a specific tag.

4.2.4.1.  Split call stream encoding

The contents of the split call stream shall be an xdrrec stream containing a finite sequence of XDR-encoded afsint_TLV structures, each of which shall be marked as a separate record (typically by calling xdrrec_endofrecord). End of sequence will be annotated by a dummy tuple containing the special tag type AFSVOL_TLV_TAG_EOS.

4.2.5.  TLV Set

The Rx procedure specification for the TLV set interface will be as follows:

struct AFSVol_TLV_store {
    afsint_TLV ts_tuple;
    afsint_TLV_value ts_qualifier;
};

proc SetVolumeTLV(
    IN afs_int32 trans,
    IN AFSVol_TLV_store tuples<AFSINT_TLV_TAG_MAX>,
    OUT afs_int32 * results<AFSINT_TLV_TAG_MAX>
) = XXX;

The call parameters are defined as follows:

trans

The trans IN parameter specifies the transaction ID returned by a previous invocation of AFSVolTransCreate.

tuples

The tuples IN parameter contains the list of TLV tuples to be set by the server.

results

The results OUT parameter contains a list of error codes, one per tuple. These error codes provide specific information regarding the success/failure of each TLV set operation. Valid error codes include: VOLSERTAGUNSUPPORTED, VOLSERTAGREADONLY, VOLSERTAGWRITEFAILED, VOLSERTAGDECODEFAILED, VOLSERTAGUNSUPPORTEDENCODING, VOLSERTAGINVALIDQUALIFIER, and VOLSERFAILEDOP.

4.2.5.1.  Call preprocessing

The SetVolumeTLV begins by scanning all elements within the tuples array. If any elements have the AFSINT_TLV_FLAG_CRITICAL bit asserted in tuples[i].ts_tuple.ts_flags, then preprocessing of the tuple must occur. For each tuple with the critical bit set, several preprocessing validation steps will be taken.

4.2.5.1.1.  Verify tag is supported

The tag stored in tuples[i].ts_tuple.tlv_tag is checked to ensure that the server supports it. In the event that the tag is not supported, then the corresponding array index in the results array will be set to VOLSERTAGUNSUPPORTED, and the RPC call abort at the conclusion of critical tuple preprocessing with error code VOLSERFAILEDOP.

4.2.5.1.2.  Verify tag is writeable

The tag stored in tuples[i].ts_tuple.tlv_flag is checked to ensure that it is a writeable property. In the event that the tag is read-only, then the corresponding array index in the results array will be set to VOLSERTAGREADONLY, and the RPC call will abort at the conclusion of critical tuple preprocessing with error code VOLSERFAILEDOP.

4.2.5.1.3.  Verify value encoding is supported

The XDR union discriminator in tuples[i].ts_tuple.tlv_value is checked to make sure that it is a supported type. If the discriminator is not a supported type, then the corresponding array index in the results array will be set to VOLSERTAGUNSUPPORTEDENCODING, and the RPC call will abort at the conclusion of critical tuple preprocessing with error code VOLSERFAILEDOP.

4.2.5.1.4.  Verify value can be decoded

The value stored in tuples[i].ts_tuple.tlv_value is checked to make sure that it can be decoded. If the wire-encoded data cannot be decoded, then the corresponding array index in the results array will be set to VOLSERTAGDECODEFAILED, and the RPC call will abort at the conclusion of critical tuple preprocessing with error code VOLSERFAILEDOP.

4.2.5.1.5.  Verify qualifier is supported

Qualifiers are specific to a given tag. If for any reason the tag-specific validation logic determines that the qualifier is invalid, it may set the corresponding array index in the results array to one of VOLSERTLVQUALIFIERUNSUPPORTEDENCODING, VOLSERTLVQUALIFIERDECODEFAILED, or VOLSERTLVQUALIFIERINVALID. As with the other validation steps, if a critical tuple fails qualifier validation, then the RPC call will abort at the conclusion of critical tuple preprocessing with error code VOLSERFAILEDOP.

4.2.5.2.  Call processing

Once the necessary validation steps have been performed, the call will perform the set operations for each tuple. Errors encountered during the processing of each tuple will be recorded in the appropriate array index of the results array. At the conclusion the RPC will either return 0 if all set operations succeeded, or VOLSERFAILEDOP if any failed.

5.  Mapping of existing metadata onto TLV namespace

Existing metadata available from several interfaces will also be exported as TLV tuples. This is being done not only for completeness, but also to prevent data races between AFSVolGetOneVolumeTLV, and the various legacy introspection interfaces.

5.1.  volintXInfo

All metadata exported via the volintXInfo XDR structure will now be exported as TLV tuples. Unless otherwise specified, the values associated with each tag shall be identical to that returned for the associated field in volintXInfo by the AFSVolXListOneVolume interface. The following tuples will be allocated to export existing members of volintXInfo:

AFSVOL_TLV_TAG_VOL_NAME

This is the TLV analogue of volintXInfo.name. This tuple MUST have a payload of type AFSINT_TLV_TYPE_STRING. The u_string payload field MUST contain a null-terminated string.

AFSVOL_TLV_TAG_VOL_STATUS

This is the TLV analogue of volintXInfo.status. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_IN_USE

This is the TLV analogue of volintXInfo.inUse. This tuple will contain a boolean value, and therefore MUST have a payload type of either: AFSINT_TLV_TYPE_TRUE, or AFSINT_TLV_TYPE_FALSE.

AFSVOL_TLV_TAG_VOL_ID

This is the TLV analogue of volintXInfo.volid. This tuple MUST have a payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_TYPE

This is the TLV analogue of volintXInfo.type. This tuple MUST have a payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_CLONE_ID

This is the TLV analogue of volintXInfo.cloneID. This tuple MUST have a payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_BACKUP_ID

This is the TLV analogue of volintXInfo.backupID. This tuple MUST have a payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_PARENT_ID

This is the TLV analogue of volintXInfo.parentID. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_COPY_DATE

This is the TLV analogue of volintXInfo.copyDate. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64. This timestamp shall be encoded using the rules specified in the forthcoming afs3 RPC refresh document.

AFSVOL_TLV_TAG_VOL_CREATE_DATE

This is the TLV analogue of volintXInfo.creationDate. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64. This timestamp shall be encoded using the rules specified in the forthcoming afs3 RPC refresh document.

AFSVOL_TLV_TAG_VOL_ACCESS_DATE

This is the TLV analogue of volintXInfo.accessDate. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64. This timestamp shall be encoded using the rules specified in the forthcoming afs3 RPC refresh document.

AFSVOL_TLV_TAG_VOL_UPDATE_DATE

This is the TLV analogue of volintXInfo.updateDate. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64. This timestamp shall be encoded using the rules specified in the forthcoming afs3 RPC refresh document.

AFSVOL_TLV_TAG_VOL_BACKUP_DATE

This is the TLV analogue of volintXInfo.backupDate. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64. This timestamp shall be encoded using the rules specified in the forthcoming afs3 RPC refresh document.

AFSVOL_TLV_TAG_VOL_SIZE

This is the TLV analogue of volintXInfo.size. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_tLV_TAG_VOL_FILE_COUNT

This is the TLV analogue of volintXInfo.filecount. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_MAX_QUOTA

This is the TLV analogue of volintXInfo.maxquota. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_DAY_USE

This is the TLV analogue of volintXInfo.dayUse. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_STAT_READS

This is the TLV analogue of volintXInfo.stat_reads. This tuple MUST have payload of type AFSINT_TLV_TYPE_OPAQUE. The opaque contents shall be an XDR-encoded structure defined as follows:

---

const VOLINT_STATS_NUM_RWINFO_FIELDS = 4;

struct AFSVol_stat_rw {
    afs_uint64 stat_rw[VOLINT_STATS_NUM_RWINFO_FIELDS];
};

Figure 8

---

AFSVOL_TLV_TAG_VOL_STAT_WRITES

This is the TLV analogue of volintXInfo.stat_reads. This tuple MUST have payload of type AFSINT_TLV_TYPE_OPAQUE. The opaque contents shall be an XDR-encoded structure as defined for AFSVOL_TLV_TAG_VOL_STAT_READS.

AFSVOL_TLV_TAG_VOL_STAT_FILE_SAME_AUTHOR

This is the TLV analogue of volintXInfo.stat_fileSameAuthor. This tuple MUST have payload of type AFSINT_TLV_TYPE_OPAQUE. The opaque contents shall be an XDR-encoded structure defined as follows:

---

const VOLINT_STATS_NUM_TIME_FIELDS = 6;

struct AFSVol_stat_time {
    afs_uint64 stat_rw[VOLINT_STATS_NUM_TIME_FIELDS];
};

Figure 9

---

AFSVOL_TLV_TAG_VOL_STAT_FILE_DIFFERENT_AUTHOR

This is the TLV analogue of volintXInfo.stat_fileDiffAuthor. This tuple MUST have payload of type AFSINT_TLV_TYPE_OPAQUE. The opaque contents shall be the XDR-encoded structure AFSVol_stat_time, as defined for AFSVOL_TLV_TAG_VOL_STAT_FILE_SAME_AUTHOR.

AFSVOL_TLV_TAG_VOL_STAT_DIR_SAME_AUTHOR

This is the TLV analogue of volintXInfo.stat_dirSameAuthor. This tuple MUST have payload of type AFSINT_TLV_TYPE_OPAQUE. The opaque contents shall be the XDR-encoded structure AFSVol_stat_time, as defined for AFSVOL_TLV_TAG_VOL_STAT_FILE_SAME_AUTHOR.

AFSVOL_TLV_TAG_VOL_STAT_DIR_DIFFERENT_AUTHOR

This is the TLV analogue of volintXInfo.stat_dirDiffAuthor. This tuple MUST have payload of type AFSINT_TLV_TYPE_OPAQUE. The opaque contents shall be the XDR-encoded structure AFSVol_stat_time, as defined for AFSVOL_TLV_TAG_VOL_STAT_FILE_SAME_AUTHOR.

5.2.  transDebugInfo

All metadata exported via the transDebugInfo XDR structure will now be exported as TLV tuples. Unless otherwise specified, the values associated with each tag shall be identical to that returned for the associated field in transDebugInfo by the AFSVolMonitor interface. The following tuples will be allocated to export existing members of transDebugInfo:

AFSVOL_TLV_TAG_VOL_TRANS_TID

This is the TLV analogue of transDebugInfo.tid. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_TRANS_TIME

This is the TLV analogue of transDebugInfo.time. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64. This timestamp shall be encoded using the rules specified in the forthcoming afs3 RPC refresh document.

AFSVOL_TLV_TAG_VOL_TRANS_CREATE_TIME

This is the TLV analogue of transDebugInfo.creationTime. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64. This timestamp shall be encoded using the rules specified in the forthcoming afs3 RPC refresh document.

AFSVOL_TLV_TAG_VOL_TRANS_RETURN_CODE

This is the TLV analogue of transDebugInfo.returnCode. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_TRANS_ATTACH_MODE

This is the TLV analogue of transDebugInfo.iflags. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_TRANS_STATUS

This is the TLV analogue of transDebugInfo.vflags This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_TRANS_FLAGS

This is the TLV analogue of transDebugInfo.tflags. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_TRANS_LAST_PROC_NAME

This is the TLV analogue of transDebugInfo.lastProcName. This tuple MUST have payload of type AFSINT_TLV_TYPE_STRING. The u_string payload field MUST contain a null-terminated string.

AFSVOL_TLV_TAG_VOL_TRANS_CALL_VALID

This is the TLV analogue of transDebugInfo.callValid. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_TRANS_READ_NEXT

This is the TLV analogue of transDebugInfo.readNext. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_TRANS_XMIT_NEXT

This is the TLV analogue of transDebugInfo.transmitNext. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64.

AFSVOL_TLV_TAG_VOL_TRANS_LAST_RECV_TIME

This is the TLV analogue of transDebugInfo.lastReceiveTime. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64. This timestamp shall be encoded using the rules specified in the forthcoming afs3 RPC refresh document.

AFSVOL_TLV_TAG_VOL_TRANS_LAST_SEND_TIME

This is the TLV analogue of transDebugInfo.lastSendTime. This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64. This timestamp shall be encoded using the rules specified in the forthcoming afs3 RPC refresh document.

5.3.  Additional de facto-standardized fields

Certain fields from the IBM AFS and OpenAFS file server's VolumeDiskData header are generally useful. In particular, several fields exported via the AFSVolGetFlags and AFSVolSetFlags RPCs should be exported via the TLV interface. The full list of supported TLV tuples are:

AFSVOL_TLV_TAG_VOL_IN_SERVICE

This tuple will contain a boolean value, and therefore MUST have a payload type of either: AFSINT_TLV_TYPE_TRUE, or AFSINT_TLV_TYPE_FALSE. When this bit is not asserted, the volume is administratively prohibited from coming online.

AFSVOL_TLV_TAG_VOL_BLESSED

This tuple will contain a boolean value, and therefore MUST have a payload type of either: AFSINT_TLV_TYPE_TRUE, or AFSINT_TLV_TYPE_FALSE. When this bit is not asserted, the volume is administratively prohibited from coming online.

AFSVOL_TLV_TAG_VOL_RESTORED_FROM_ID

This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64. When this field is non-zero, it contains the volume ID contained in the dump from which it was restored.

AFSVOL_TLV_TAG_VOL_DESTROYED

This tuple will contain a boolean value, and therefore MUST have a payload type of either: AFSINT_TLV_TYPE_TRUE, or AFSINT_TLV_TYPE_FALSE. When this bit is asserted, this volume is flagged for deletion.

AFSVOL_TLV_TAG_VOL_NEEDS_SALVAGE

This tuple will contain a boolean value, and therefore MUST have a payload type of either: AFSINT_TLV_TYPE_TRUE, or AFSINT_TLV_TYPE_FALSE. When this bit is asserted, this volume requires a salvage.

AFSVOL_TLV_TAG_VOL_OFFLINE_MESSAGE

This tuple MUST have payload of type AFSINT_TLV_TYPE_STRING. The u_string payload field MUST contain a null-terminated string. This field stores an administrative message to indicate why the volume is offline.

AFSVOL_TLV_TAG_VOL_EXPIRATION_DATE

This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64. This timestamp shall be encoded using the rules specified in the forthcoming afs3 RPC refresh document. To the best knowledge of the authors, this field is not standardized by any implementation.

AFSVOL_TLV_TAG_VOL_RESERVATION

This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64. This field, otherwise known as minquota, specifies the amount of storage (in units of 1024 octets) that are reserved on the underlying storage for use by this volume.

6.  Extended volume state exportation

In addition to exporting the existing volser state, DAFS state metadata will also be exported via the TLV interface. Specifically, an extended volume state field, and a raw DAFS state debugging tag, will be exported.

6.1.  Mapped volume states

Given that volume state information is useful across all server implementations, a collection of generic states shall be standardized. The following states are initially defined in the namespace:

AFSVOL_VOLUME_STATE_OUT_OF_SERVICE

This volume is administratively out of service. For example, the IBM AFS and OpenAFS implementations both permit an administrator to force a volume offline by mutating the blessed and inService bits.

AFSVOL_VOLUME_STATE_OFFLINE

This volume is offline for reasons other than administrative intervention.

AFSVOL_VOLUME_STATE_READY

This volume is not online, but it is ready to be brought online by the server on-demand.

AFSVOL_VOLUME_STATE_ONLINE

This volume is online.

AFSVOL_VOLUME_STATE_BUSY

This volume is busy performing some operation which requires exclusive access.

AFSVOL_VOLUME_STATE_IO_BUSY

This volume is busy performing an I/O operation which requires exclusive access.

AFSVOL_VOLUME_STATE_SALVAGING

This volume is currently being salvaged in the background.

AFSVOL_VOLUME_STATE_SALVAGE_NEEDED

This volume is offline, and will require a salvage before it can be brought online.

AFSVOL_VOLUME_STATE_ERROR

This volume has been forced offline due to a non-recoverable error. Manual intervention by an administrator will be necessary to bring this volume back to an operable state.

AFSVOL_VOLUME_STATE_VOLUME_OPERATION

This volume is currently offline because a volume transaction requires exclusive access.

6.2.  Mapped process types

It is useful to be able to track volume ownership by process type. In order to do this, a new program type namespace must be defined. The following types are initially defined in the program type namespace:

AFSINT_PROGRAM_TYPE_FILE_SERVER

Refers to an afs file server process (Rx udp port 7000, service ID 0).

AFSINT_PROGRAM_TYPE_VOLUME_SERVER

Refers to an afs volume server process (Rx udp port 7005, service ID 4).

AFSINT_PROGRAM_TYPE_SALVAGER

Refers to an afs stand-alone salvager process.

AFSINT_PROGRAM_TYPE_SALVAGE_SERVER

Refers to an OpenAFS DAFS salvage server process.

AFSINT_PROGRAM_TYPE_VOLUME_UTILITY

Refers to any ancillary stand-alone volume utility process.

6.3.  TLV tuples

Volume state will be exported via three new TLV tuples:

AFSVOL_TLV_TAG_VOL_STATE_MAPPED

This tuple MUST have payload of type AFSINT_TLV_TYPE_UINT64. The u_64 payload shall contain a volume state enumeration value, as defined in [sub:Mapped-volume-states].

AFSVOL_TLV_TAG_VOL_STATE_DAFS_RAW

For servers exporting capability AFSVOL_CAPABILITY_DAFS, this payload MUST be of type AFSINT_TLV_TYPE_OPAQUE. Encoding of raw state is unspecified and implementation-private.

AFSVOL_TLV_TAG_VOL_OWNING_PROCESS

For servers exporting capability AFSVOL_CAPABILITY_DAFS, this payload MUST be of type AFSINT_TLV_TYPE_UINT64. The u_64 payload shall contain a program type enumeration value, as defined in [sub:Mapped-process-types].

7.  Acknowledgements

We would like to thank all of the participants at the 2009 Edinburgh AFS hackathon for their input into the design of this TLV mechanism. Alistair Ferguson has provided much useful feedback, especially with regard to backwards compatibility and discriminated union type identifier namespace allocations. Andrew Deason and Michael Meffie have provided considerable input with regard to the discriminated union XDR decoding problem, GCO registrar and namespace allocation concerns, what metadata should be exported in the initial revision, the notion of data qualifiers, as well as commentary about how they envision this extension being used to support future protocol extensions.

8.  IANA Considerations

This memo includes no request to IANA.

9.  GCO Registrar Considerations

The Grand Central Registrar will need to consider several assigned numbers requests.

9.1.  Namespace allocations

First and foremost, this memo requests that the GCO Registrar assume control over several new namespaces:

1. AFSVol capability bit namespace
2. AFS-3 TLV payload type namespace
3. AFSVol TLV tag namespace
4. AFSVol mapped volume state namespace
5. AFS-3 program type namespace

9.2.  Assigned numbers allocations

In addition to requesting the allocation of new namespaces, this memo also requests several new allocations within existing assigned numbers namespaces.

9.2.1.  VICED capability bits

One new capability bit is requested:

• VICED_CAPABILITY_DAFS

9.2.2.  AFSVol capability bits

Two new capability bits are requested:

• AFSVOL_CAPABILITY_DAFS
• AFSVOL_CAPABILITY_TLV

9.2.3.  AFS-3 TLV payload types

The following payload type allocations are requested:

• AFSINT_TLV_TYPE_NULL
• AFSINT_TLV_TYPE_TRUE
• AFSINT_TLV_TYPE_FALSE
• AFSINT_TLV_TYPE_UINT64
• AFSINT_TLV_TYPE_UUID
• AFSINT_TLV_TYPE_STRING
• AFSINT_TLV_TYPE_OPAQUE

9.2.4.  AFSVol TLV tags

The following tag allocations are requested:

• AFSVOL_TLV_TAG_VOL_NAME
• AFSVOL_TLV_TAG_VOL_STATUS
• AFSVOL_TLV_TAG_VOL_IN_USE
• AFSVOL_TLV_TAG_VOL_ID
• AFSVOL_TLV_TAG_VOL_TYPE
• AFSVOL_TLV_TAG_VOL_CLONE_ID
• AFSVOL_TLV_TAG_VOL_BACKUP_ID
• AFSVOL_TLV_TAG_VOL_PARENT_ID
• AFSVOL_TLV_TAG_VOL_COPY_DATE
• AFSVOL_TLV_TAG_VOL_CREATE_DATE
• AFSVOL_TLV_TAG_VOL_ACCESS_DATE
• AFSVOL_TLV_TAG_VOL_UPDATE_DATE
• AFSVOL_TLV_TAG_VOL_BACKUP_DATE
• AFSVOL_TLV_TAG_VOL_SIZE
• AFSVOL_TLV_TAG_VOL_FILE_COUNT
• AFSVOL_TLV_TAG_VOL_MAX_QUOTA
• AFSVOL_TLV_TAG_VOL_DAY_USE
• AFSVOL_TLV_TAG_VOL_STAT_READS
• AFSVOL_TLV_TAG_VOL_STAT_WRITES
• AFSVOL_TLV_TAG_VOL_STAT_FILE_SAME_AUTHOR
• AFSVOL_TLV_TAG_VOL_STAT_FILE_DIFFERENT_AUTHOR
• AFSVOL_TLV_TAG_VOL_STAT_DIR_SAME_AUTHOR
• AFSVOL_TLV_TAG_VOL_STAT_DIR_DIFFERENT_AUTHOR
• AFSVOL_TLV_TAG_VOL_TRANS_ID
• AFSVOL_TLV_TAG_VOL_TRANS_TIME
• AFSVOL_TLV_TAG_VOL_TRANS_CREATE_TIME
• AFSVOL_TLV_TAG_VOL_TRANS_RETURN_CODE
• AFSVOL_TLV_TAG_VOL_TRANS_ATTACH_MODE
• AFSVOL_TLV_TAG_VOL_TRANS_STATUS
• AFSVOL_TLV_TAG_VOL_TRANS_FLAGS
• AFSVOL_TLV_TAG_VOL_TRANS_LAST_PROC_NAME
• AFSVOL_TLV_TAG_VOL_TRANS_CALL_VALID
• AFSVOL_TLV_TAG_VOL_TRANS_READ_NEXT
• AFSVOL_TLV_TAG_VOL_TRANS_XMIT_NEXT
• AFSVOL_TLV_TAG_VOL_TRANS_LAST_RECV_TIME
• AFSVOL_TLV_TAG_VOL_TRANS_LAST_SEND_TIME
• AFSVOL_TLV_TAG_VOL_IN_SERVICE
• AFSVOL_TLV_TAG_VOL_BLESSED
• AFSVOL_TLV_TAG_VOL_RESTORED_FROM_ID
• AFSVOL_TLV_TAG_VOL_DESTROYED
• AFSVOL_TLV_TAG_VOL_NEEDS_SALVAGE
• AFSVOL_TLV_TAG_VOL_OFFLINE_MESSAGE
• AFSVOL_TLV_TAG_VOL_EXPIRATION_DATE
• AFSVOL_TLV_TAG_VOL_RESERVATION
• AFSVOL_TLV_TAG_VOL_STATE_MAPPED
• AFSVOL_TLV_TAG_VOL_STATE_RAW
• AFSVOL_TLV_TAG_VOL_OWNING_PROCESS
• AFSVOL_TLV_TAG_EOS

9.2.5.  VOLS error table

Within the VOLS error table (offset 1492325120), several new codes need to be allocated:

• VOLSERTAGUNSUPPORTED
• VOLSERTAGREADONLY
• VOLSERTAGWRITEFAILED
• VOLSERTAGDECODEFAILED
• VOLSERTAGUNSUPPORTEDENCODING
• VOLSERTLVQUALIFIERUNSUPPORTEDENCODING
• VOLSERTLVQUALIFIERDECODEFAILED
• VOLSERTLVQUALIFIERINVALID

9.2.6.  AFSVol mapped volume names

Within the new AFSVol mapped volume state namespace, the following allocations are requested:

• AFSVOL_VOLUME_STATE_OUT_OF_SERVICE
• AFSVOL_VOLUME_STATE_OFFLINE
• AFSVOL_VOLUME_STATE_READY
• AFSVOL_VOLUME_STATE_ONLINE
• AFSVOL_VOLUME_STATE_BUSY
• AFSVOL_VOLUME_STATE_IO_BUSY
• AFSVOL_VOLUME_STATE_SALVAGING
• AFSVOL_VOLUME_STATE_SALVAGE_NEEDED
• AFSVOL_VOLUME_STATE_ERROR
• AFSVOL_VOLUME_STATE_VOLUME_OPERATION

9.2.7.  AFS-3 program types

Within the new AFS program type namespace, the following allocations are requested:

• AFSINT_PROGRAM_TYPE_FILE_SERVER
• AFSINT_PROGRAM_TYPE_VOLUME_SERVER
• AFSINT_PROGRAM_TYPE_SALVAGER
• AFSINT_PROGRAM_TYPE_SALVAGE_SERVER
• AFSINT_PROGRAM_TYPE_VOLUME_UTILITY

10.  Security Considerations

Security and authorization issues are tag-specific. The legacy AFSVol RPCs permitted rxnull connections to perform the four ListVolume RPCs, and AFSVolMonitor. Arguably, it is time to re-evaluate this decision, and restrict access to certain tags, as they do permit potentially sensitive volume or operational metadata to leak onto public networks.

11.  References

11.1. Normative References

11.2. Informative References

Appendix A.  XDR Grammar for FS-CM Capabilities Mechanism

const AFSCAPABILITIESMAX = 196;

typedef afs_uint32 Capabilities<AFSCAPABILITIESMAX>;

/* Viced Capability Flags */
const VICED_CAPABILITY_ERRORTRANS   = 0x0001;
const VICED_CAPABILITY_64BITFILES   = 0x0002;
const VICED_CAPABILITY_WRITELOCKACL = 0x0004;
const VICED_CAPABILITY_SANEACLS     = 0x0008;

/* Cache Manager Capability Flags */
const CLIENT_CAPABILITY_ERRORTRANS  = 0x0001;

Authors' Addresses