idnits 2.17.1 draft-tkeiser-afs3-volser-tlv-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- -- The document has an IETF Trust Provisions (28 Dec 2009) Section 6.c(ii) Publication Limitation clause. If this document is intended for submission to the IESG for publication, this constitutes an error. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([I-D.wilkinson-afs3-standardisation]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 11, 2012) is 4244 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '7' on line 2456 -- Looks like a reference, but probably isn't: '0' on line 1458 -- Looks like a reference, but probably isn't: '1' on line 1459 -- Looks like a reference, but probably isn't: '2' on line 1460 -- Looks like a reference, but probably isn't: '3' on line 1461 -- Looks like a reference, but probably isn't: '4' on line 1462 -- Looks like a reference, but probably isn't: '5' on line 1463 -- Looks like a reference, but probably isn't: '6' on line 1464 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 N/A T. Keiser 3 Internet-Draft Sine Nomine 4 Intended status: Informational S. Jenkins 5 Expires: March 15, 2013 6 A. Deason, Ed. 7 Sine Nomine 8 September 11, 2012 10 AFSVol Tag-Length-Value Remote Procedure Call Extensions 11 draft-tkeiser-afs3-volser-tlv-04 13 Abstract 15 AFS-3 is a distributed file system based upon prototypes developed at 16 Carnegie Mellon University during the 1980s. AFS-3 heavily leverages 17 Remote Procedure Calls (RPCs) as the foundation for its distributed 18 architecture. This memo extends the volume management interface to 19 support getting and setting of AFS volume attributes via an 20 extensible Tag-Length-Value (TLV) encoding, which is based upon AFS-3 21 extensible discriminated unions. TLV-based get and set RPCs are 22 specified, along with a tag enumeration RPC. 24 In addition, tags are allocated for existing volume and transaction 25 metadata, and implementation-private tags are allocated for metadata 26 related to the OpenAFS Demand Attach File Server, and the RxOSD 27 protocol suite. 29 Internet Draft Comments 31 Comments regarding this draft are solicited. Please include the 32 AFS-3 protocol standardization mailing list 33 (afs3-standardization@openafs.org) as a recipient of any comments. 35 AFS-3 Document State 37 This document is in state "draft", as per the document state 38 definitions set forth in [I-D.wilkinson-afs3-standardisation]. 40 Status of this Memo 42 This Internet-Draft is submitted in full conformance with the 43 provisions of BCP 78 and BCP 79. This document may not be modified, 44 and derivative works of it may not be created, and it may not be 45 published except as an Internet-Draft. 47 Internet-Drafts are working documents of the Internet Engineering 48 Task Force (IETF). Note that other groups may also distribute 49 working documents as Internet-Drafts. The list of current Internet- 50 Drafts is at http://datatracker.ietf.org/drafts/current/. 52 Internet-Drafts are draft documents valid for a maximum of six months 53 and may be updated, replaced, or obsoleted by other documents at any 54 time. It is inappropriate to use Internet-Drafts as reference 55 material or to cite them other than as "work in progress." 57 This Internet-Draft will expire on March 15, 2013. 59 Copyright Notice 61 Copyright (c) 2012 IETF Trust and the persons identified as the 62 document authors. All rights reserved. 64 This document is subject to BCP 78 and the IETF Trust's Legal 65 Provisions Relating to IETF Documents 66 (http://trustee.ietf.org/license-info) in effect on the date of 67 publication of this document. Please review these documents 68 carefully, as they describe your rights and restrictions with respect 69 to this document. 71 Table of Contents 73 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 74 1.1. Motivations . . . . . . . . . . . . . . . . . . . . . . . 5 75 1.2. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 6 76 1.3. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 6 77 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 7 78 3. New Capability Bit Allocations . . . . . . . . . . . . . . . . 8 79 3.1. VICED_CAPABILITY_DAFS . . . . . . . . . . . . . . . . . . 8 80 3.2. AFSVOL_CAPABILITY_DAFS . . . . . . . . . . . . . . . . . . 8 81 3.3. AFSVOL_CAPABILITY_TLV . . . . . . . . . . . . . . . . . . 8 82 4. TLV Interface . . . . . . . . . . . . . . . . . . . . . . . . 8 83 4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . . . 9 84 4.1.1. Data Value Types . . . . . . . . . . . . . . . . . . . 11 85 4.1.2. TLV Flags . . . . . . . . . . . . . . . . . . . . . . 14 86 4.1.3. Use of AFSVOL_TLV_TYPE_OPAQUE . . . . . . . . . . . . 15 87 4.2. Qualifiers . . . . . . . . . . . . . . . . . . . . . . . . 15 88 5. AFSVol TLV Interface . . . . . . . . . . . . . . . . . . . . . 16 89 5.1. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 16 90 5.2. Tag Introspection . . . . . . . . . . . . . . . . . . . . 17 91 5.2.1. Tag Namespace Cache Coherence . . . . . . . . . . . . 18 92 5.3. TLV Get . . . . . . . . . . . . . . . . . . . . . . . . . 18 93 5.4. TLV Streaming Get . . . . . . . . . . . . . . . . . . . . 20 94 5.4.1. Split call stream encoding . . . . . . . . . . . . . . 22 95 5.5. TLV Set . . . . . . . . . . . . . . . . . . . . . . . . . 22 96 5.5.1. Call preprocessing . . . . . . . . . . . . . . . . . . 24 97 5.5.1.1. Verify tag is supported . . . . . . . . . . . . . 24 98 5.5.1.2. Verify tag is writeable . . . . . . . . . . . . . 25 99 5.5.1.3. Verify value encoding is supported . . . . . . . . 25 100 5.5.1.4. Verify value can be decoded . . . . . . . . . . . 25 101 5.5.1.5. Verify qualifier is supported . . . . . . . . . . 25 102 5.5.2. Call processing . . . . . . . . . . . . . . . . . . . 25 103 6. Mapping of existing metadata onto TLV namespace . . . . . . . 26 104 6.1. volintXInfo . . . . . . . . . . . . . . . . . . . . . . . 26 105 6.2. transDebugInfo . . . . . . . . . . . . . . . . . . . . . . 29 106 6.3. Additional de facto-standardized fields . . . . . . . . . 31 107 6.4. Day-of-week usage statistics . . . . . . . . . . . . . . . 33 108 6.4.1. Qualifiers . . . . . . . . . . . . . . . . . . . . . . 33 109 6.4.1.1. NULL qualifier . . . . . . . . . . . . . . . . . . 33 110 6.4.1.2. UINT64 qualifier . . . . . . . . . . . . . . . . . 34 111 6.4.2. Calendar day correlation . . . . . . . . . . . . . . . 34 112 7. Extended volume state exportation . . . . . . . . . . . . . . 34 113 7.1. Volume state explanations . . . . . . . . . . . . . . . . 34 114 7.2. Mapped process types . . . . . . . . . . . . . . . . . . . 36 115 7.3. TLV tuples . . . . . . . . . . . . . . . . . . . . . . . . 37 116 8. AFS-3 Object Storage Extensions Policy Attributes . . . . . . 38 117 9. Backward Compatibility . . . . . . . . . . . . . . . . . . . . 39 118 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 39 119 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 40 120 12. AFS Assign Numbers Registrar Considerations . . . . . . . . . 40 121 12.1. Namespace allocations . . . . . . . . . . . . . . . . . . 40 122 12.1.1. AFSVol TLV Payloads . . . . . . . . . . . . . . . . . 40 123 12.1.2. AFSVol TLV Tags . . . . . . . . . . . . . . . . . . . 41 124 12.1.3. AFSVol TLV Flags . . . . . . . . . . . . . . . . . . . 42 125 12.1.4. AFSVol DoW Stats Flags . . . . . . . . . . . . . . . . 43 126 12.1.5. AFSVol Vol State Expls . . . . . . . . . . . . . . . . 43 127 12.1.6. AFSVol Program Types . . . . . . . . . . . . . . . . . 44 128 12.2. Assigned numbers allocations . . . . . . . . . . . . . . . 45 129 12.2.1. VICED Capability bits . . . . . . . . . . . . . . . . 45 130 12.2.2. AFSVol Capabilities . . . . . . . . . . . . . . . . . 45 131 12.2.3. AFSVol TLV Payloads . . . . . . . . . . . . . . . . . 45 132 12.2.4. AFSVol TLV Tags . . . . . . . . . . . . . . . . . . . 46 133 12.2.5. AFSVol TLV Flags . . . . . . . . . . . . . . . . . . . 49 134 12.2.6. AFSVol DoW Stats Flags . . . . . . . . . . . . . . . . 49 135 12.2.7. VOLS Error Table . . . . . . . . . . . . . . . . . . . 50 136 12.2.8. AFSVol Vol State Expls . . . . . . . . . . . . . . . . 50 137 12.2.9. AFSVol Program Types . . . . . . . . . . . . . . . . . 51 138 13. Security Considerations . . . . . . . . . . . . . . . . . . . 51 139 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 51 140 14.1. Normative References . . . . . . . . . . . . . . . . . . . 51 141 14.2. Informative References . . . . . . . . . . . . . . . . . . 52 142 Appendix A. Sample Rx RPC-L Definition for AFSVol TLV 143 Mechanism . . . . . . . . . . . . . . . . . . . . . . 53 144 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 59 146 1. Introduction 148 AFS-3 [CMU-ITC-88-062] [CMU-ITC-87-068] is a distributed file system 149 that has its origins in the VICE project [CMU-ITC-84-020] 150 [CMU-ITC-85-039] at the Carnegie Mellon University Information 151 Technology Center [CMU-ITC-83-025] a joint venture between CMU and 152 IBM. VICE later became AFS when CMU moved development to a new 153 commercial venture called Transarc Corporation, which later became 154 IBM Pittsburgh Labs. AFS-3 is a suite of un-standardized network 155 protocols based on a remote procedure call (RPC) suite known as Rx. 156 While de jure standards for AFS-3 fail to exist, the various AFS-3 157 implementations have agreed upon certain de facto standards, largely 158 helped by the existence of an open source fork called OpenAFS that 159 has served the role of reference implementation. In addition to 160 using OpenAFS as a reference, IBM wrote and donated developer 161 documentation that contains somewhat outdated specifications for the 162 Rx protocol and all AFS-3 remote procedure calls, as well as a 163 detailed description of the AFS-3 system architecture. 165 The AFS-3 architecture consists of many administrative domains called 166 "cells" [CMU-ITC-88-070] which are glued together to form a globally 167 distributed file system. Each cell consists of: client nodes, which 168 run cache manager daemons; file servers, which run file server 169 daemons and volume server daemons; and database server nodes, which 170 can run volume location database servers, protection database 171 servers, backup database servers, or several other obscure and/or 172 deprecated database services. 174 This memo focuses on the volume server [AFS3-VVL] component of AFS-3. 175 The volume server provides an RPC interface for managing AFS volumes. 176 Volumes are the unit of storage administration in AFS-3. Each volume 177 contains a subtree of the file system, along with special directory 178 entries called mount points, which are used to link volumes together 179 into a (potentially cyclic) directed graph. Mount points can cross 180 cell boundaries, thus permitting construction of a cross- 181 organizational, globally distributed, location-transparent file 182 system. The file system is location-transparent because mount points 183 contain volume names and cell names (which are resolved to locations 184 by contacting the appropriate cell's volume location database), 185 rather than encoding the data's physical location directly in the 186 pointer. This memo extends the AFS-3 volume server RPC interface 187 with a suite of new RPCs that provide extensible volume metadata get 188 and set operations. 190 1.1. Motivations 192 The current AFSVol volume metadata introspection routines use hard- 193 coded XDR [RFC4506] structure definitions. This significantly limits 194 protocol extensibility because new remote procedure calls and 195 structure definitions must be defined during each protocol revision. 196 To some degree, this has been due to the lack of protocol standards 197 documents: certain sites co-opted unused protocol fields for private 198 uses, thus precluding the standards process from reclaiming these 199 fields (without breaking existing deployments). Hence, each time new 200 functionality is required, a new RPC--and, typically, new XDR data 201 structures--need to be defined. This is a rather expensive process-- 202 both in terms of standardization, and implementation. Frequently, 203 this leads to a desire to postpone protocol feature enhancements 204 until many changes can be aggregated into a monolithic protocol 205 upgrade. 207 This memo introduces a new tag-length-value (TLV) encoding mechanism 208 based upon the AFS-3 extensible discriminated union primitive type 209 [I-D.keiser-afs3-xdr-union]. This TLV encoding is utilized for 210 getting and setting AFS-3 volume metadata. The key advantage of this 211 design is that new TLV tuples can be allocated without defining a new 212 RPC. Furthermore, because ext-union includes a length field in the 213 encoding, it is always possible for a peer to decode the remainder of 214 the XDR stream--even when a tag (and, thus, its XDR encoding) is 215 unrecognized. Hence, decode error handling can happen at the 216 application layer, instead of deep within the Rx protocol stack. 218 As the TLV changes require the addition of several new RPC interfaces 219 (that are intended to eventually supplant extant interfaces), it is 220 logical to add AFSVol capabilities [I-D.keiser-afs3-capabilities] for 221 these new interfaces. 223 1.2. Goals 225 This memo aims to standardize a new TLV encoding mechanism for volume 226 metadata. In addition, this memo will standardize the TLV encoding 227 of volume metadata which is currently available via several AFSVol 228 XDR structures, as well as specify the encoding of several new pieces 229 of AFS-3 volume metadata that are not currently available via the 230 AFSVol interface. For example, metadata specific to the OpenAFS 231 Demand Attach File Server [DAFS] will be made available via the 232 AFSVol service, whereas in the past it was only available locally on 233 the file server machine via a proprietary interprocess communication 234 mechanism. 236 1.3. Abbreviations 237 AFS - Historically, AFS stood for the Andrew File System; AFS 238 no longer stands for anything 240 afscbint - AFS-3 Cache Manager RPC Interface Definition 242 afsint - AFS-3 File Server RPC Interface Definition 244 AFSVol - AFS Volume Server Rx RPC Implementation 246 CM - AFS-3 Cache Manager 248 DAFS - OpenAFS Demand Attach File Server 250 FS - AFS-3 File Server 252 RPC - Remote Procedure Call 254 RPC-L - Rx RPC Interface Definition Language (fork of ONC RPC 255 [RFC5531] .x file format) 257 Rx - The Remote Procedure Call mechanism utilized by AFS-3 258 [AFS3-RX] 260 RXAFS - AFS File Server Rx RPC Implementation 262 RXAFSCB - AFS Cache Manager Rx RPC Implementation 264 TLV - Tag-Length-Value encoding 266 TSV - Tag nameSpace Version ordinal 268 TTL - Time to Live for cached data 270 volint - AFS-3 Volume Server RPC Interface Definition 272 volser - AFS-3 Volume Server 274 XDR - eXternal Data Representation [RFC4506] 276 2. Conventions 278 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 279 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 280 document are to be interpreted as described in RFC 2119 [RFC2119]. 282 3. New Capability Bit Allocations 284 3.1. VICED_CAPABILITY_DAFS 286 When this capability bit is asserted, the file server is advertising 287 that it supports Demand Attach File Server version 1 protocol 288 semantics. Specifically, DAFS v1 semantics imply that the following 289 invariants MAY be violated by the fileserver: 291 1. any indication, which is visible to an afsint client, that a file 292 server is restarting implies that all call back state will be 293 invalidated; and 295 2. RXAFS_GetVolumeStatus will return exact on-disk header state for 296 the volume in question. 298 3.2. AFSVOL_CAPABILITY_DAFS 300 When this capability bit is asserted, the volserver is advertising 301 that it supports Demand Attach File Server version 1 protocol 302 semantics. Specifically, DAFS v1 semantics imply that the following 303 invariants MAY be violated by the volserver: 305 1. RPCs returning volintInfo (AFSVolListVolumes, 306 AFSVolListOneVolume) and volintXInfo (AFSVolXListVolumes, 307 AFSVolXListOneVolume) will return exact on-disk header state for 308 the volume in question 310 In addition, the combination of AFSVOL_CAPABILITY_DAFS and 311 AFSVOL_CAPABILITY_TLV MAY imply that the tag 312 AFSVOL_TLV_TAG_VOL_STATE_DAFS_RAW exists. However, this implication 313 SHOULD NOT be relied upon, as DAFS may evolve to the point where 314 AFSVOL_TLV_TAG_VOL_STATE_DAFS_RAW has to be deprecated. When both of 315 these capabilities are asserted, the client SHOULD still gracefully 316 handle the VOLSER_TAG_UNSUPPORTED error for 317 AFSVOL_TLV_TAG_VOL_STATE_DAFS_RAW. 319 3.3. AFSVOL_CAPABILITY_TLV 321 Assertion of this capability bit indicates the ability to service the 322 RPC calls described in Section 4. 324 4. TLV Interface 326 A new suite of RPCs will be standardized to get/set tag-length-value 327 tuples, and to enumerate supported tags. The tag namespace will be 328 controlled by the AFS Assigned Numbers Registrar as an assigned 329 numbers namespace. 331 4.1. Encoding 333 The TLV data will be encoded using the AFS-3 extensible discriminated 334 union [I-D.keiser-afs3-xdr-union]. The RPC-L specification for the 335 base TLV types is as follows (NB: this is pseudocode; a less-concise, 336 but machine-parseable version of this specification is included in 337 Appendix A). 339 /* registrar-controlled tag namespace */ 340 enum AFSVol_TLV_tag { 341 ... 342 }; 344 const AFSVOL_TLV_TAG_MAX = 1024; /* upper-bound on number of 345 * TLV tuples per RPC */ 346 const AFSVOL_TLV_OPAQUE_MAX = 262144; /* upper-bound on size of 347 * value payload */ 348 const AFSVOL_TLV_TIME_MAX = 21845; /* upper-bound on length of 349 AFSTime vector payload */ 350 const AFSVOL_TLV_UINT64_MAX = 32768; /* upper-bound on length of 351 uint64 vector payload */ 353 enum AFSVol_TLV_type { 354 AFSVOL_TLV_TYPE_NULL = 0, 355 AFSVOL_TLV_TYPE_TRUE = 1, 356 AFSVOL_TLV_TYPE_FALSE = 2, 357 AFSVOL_TLV_TYPE_UINT64 = 3, 358 AFSVOL_TLV_TYPE_UINT64_VEC = 4, 359 AFSVOL_TLV_TYPE_INT64 = 5, 360 AFSVOL_TLV_TYPE_INT64_VEC = 6, 361 AFSVOL_TLV_TYPE_UUID = 7, 362 AFSVOL_TLV_TYPE_STRING = 8, 363 AFSVOL_TLV_TYPE_TIME_ABS = 9, 364 AFSVOL_TLV_TYPE_TIME_ABS_VEC = 10, 365 AFSVOL_TLV_TYPE_TIME_REL = 11, 366 AFSVOL_TLV_TYPE_TIME_REL_VEC = 12, 367 AFSVOL_TLV_TYPE_VOL_ID = 13, 368 AFSVOL_TLV_TYPE_VOL_ID_VEC = 14, 369 AFSVOL_TLV_TYPE_PART_ID = 15, 370 AFSVOL_TLV_TYPE_PART_ID_VEC = 16, 371 AFSVOL_TLV_TYPE_DISK_BLOCKS = 17, 372 AFSVOL_TLV_TYPE_STAT_COUNTER = 18, 373 AFSVOL_TLV_TYPE_STAT_GAUGE = 19, 374 AFSVOL_TLV_TYPE_BIT64 = 20, 375 AFSVOL_TLV_TYPE_VOL_DOW_USE = 21, 376 AFSVOL_TLV_TYPE_OPAQUE = 22 378 }; 380 ext-union AFSVol_TLV_value switch(AFSVol_TLV_type type) { 381 case AFSVOL_TLV_TYPE_NULL: 382 case AFSVOL_TLV_TYPE_TRUE: 383 case AFSVOL_TLV_TYPE_FALSE: 384 void; 386 case AFSVOL_TLV_TYPE_UINT64: 387 case AFSVOL_TLV_TYPE_VOL_ID: 388 case AFSVOL_TLV_TYPE_PART_ID: 389 case AFSVOL_TLV_TYPE_DISK_BLOCKS: 390 case AFSVOL_TLV_TYPE_STAT_COUNTER: 391 case AFSVOL_TLV_TYPE_BIT64: 392 afs_uint64 u_u64; 394 case AFSVOL_TLV_TYPE_INT64: 395 case AFSVOL_TLV_TYPE_STAT_GAUGE: 396 afs_int64 u_s64; 398 case AFSVOL_TLV_TYPE_UINT64_VEC: 399 case AFSVOL_TLV_TYPE_VOL_ID_VEC: 400 case AFSVOL_TLV_TYPE_PART_ID_VEC: 401 afs_uint64 u_u64_vec; 403 case AFSVOL_TLV_TYPE_INT64_VEC: 404 afs_int64 u_s64_vec; 406 case AFSVOL_TLV_TYPE_TIME_ABS: 407 AFSTime u_time_abs; 409 case AFSVOL_TLV_TYPE_TIME_REL: 410 AFSRelTimestamp u_time_rel; 412 case AFSVOL_TLV_TYPE_TIME_ABS_VEC: 413 AFSTime u_time_abs_vec; 415 case AFSVOL_TLV_TYPE_TIME_REL_VEC: 416 AFSRelTimestamp u_time_rel_vec; 418 case AFSVOL_TLV_TYPE_UUID: 419 afsUUID u_uuid; 421 case AFSVOL_TLV_TYPE_STRING: 422 string u_string; 424 case AFSVOL_TLV_TYPE_VOL_DOW_USE: 425 /* type defined later in this memo */ 426 AFSVol_stat_use_per_dow u_vol_dow_use; 428 case AFSVOL_TLV_TYPE_OPAQUE: 429 opaque u_opaque; 430 }; 432 const AFSVOL_TLV_FLAG_UNSUPPORTED = 0x1; 433 const AFSVOL_TLV_FLAG_READ_ERROR = 0x2; 434 const AFSVOL_TLV_FLAG_CRITICAL = 0x4; 435 const AFSVOL_TLV_FLAG_QUALIFIER_NO_MATCH = 0x8; 436 const AFSVOL_TLV_FLAG_MORE = 0x10; 437 const AFSVOL_TLV_FLAG_OBJ_NOT_SUPP = 0x20; 439 struct AFSVol_TLV { 440 afs_uint32 tlv_tag; 441 afs_uint32 tlv_flags; 442 AFSVol_TLV_value tlv_value; 443 }; 445 TLV XDR pseudocode 447 Figure 1 449 4.1.1. Data Value Types 451 The core of the TLV definition above is the AFS-3 extensible 452 discriminated union primitive type. The following discriminators are 453 initially defined in this memo: 455 AFSVOL_TLV_TYPE_NULL = 0 457 This shall map to type XDR void in the AFSVol_TLV_value union. 459 AFSVOL_TLV_TYPE_TRUE = 1 461 This shall map to type XDR void in the AFSVol_TLV_value union. 462 It is used to communicate the boolean value true. 464 AFSVOL_TLV_TYPE_FALSE = 2 466 This shall map to type XDR void in the AFSVol_TLV_value union. 467 It is used to communicate the boolean value false. 469 AFSVOL_TLV_TYPE_UINT64 = 3 471 This shall map to type afs_uint64 in the AFSVol_TLV_value union. 472 The semantics of this field are defined by the tag. 474 AFSVOL_TLV_TYPE_UINT64_VEC = 4 476 This shall map to an XDR variable length vector of up to 32768 477 afs_uint64 values. The semantics of this field are defined by 478 the tag. 480 AFSVOL_TLV_TYPE_INT64 = 5 482 This shall map to type afs_int64 in the AFSVol_TLV_value union. 483 The semantics of this field are defined by the tag. 485 AFSVOL_TLV_TYPE_INT64_VEC = 6 487 This shall map to an XDR variable length vector of up to 32768 488 afs_int64 values. The semantics of this field are defined by the 489 tag. 491 AFSVOL_TLV_TYPE_UUID = 7 493 This shall map to an afsUUID 494 [I-D.keiser-afs3-xdr-primitive-types] type. 496 AFSVOL_TLV_TYPE_STRING = 8 498 This shall map to an XDR string of maximum length 262144. The 499 semantics of this field are defined by the tag. 501 AFSVOL_TLV_TYPE_TIME_ABS = 9 503 This shall map to an AFSTime in the AFSVol_TLV_value union. This 504 absolute timestamp shall be encoded using the rules specified in 505 the AFS-3 time type specification [I-D.deason-afs3-type-time]. 507 AFSVOL_TLV_TYPE_TIME_ABS_VEC = 10 509 This shall map to an XDR variable length vector of up to 21845 510 AFSTime values in the AFSVol_TLV_value union. The absolute 511 timestamp contained within each vector element shall be encoded 512 using the rules specified in the AFS-3 time type specification 513 [I-D.deason-afs3-type-time]. 515 AFSVOL_TLV_TYPE_TIME_REL = 11 517 This shall map to an AFSRelTimestamp in the AFSVol_TLV_value 518 union. This relative timestamp (time interval) shall be encoded 519 using the rules specified in the AFS-3 time type specification 520 [I-D.deason-afs3-type-time]. 522 AFSVOL_TLV_TYPE_TIME_REL_VEC = 12 524 This shall map to an XDR variable length vector of up to 32768 525 AFSRelTimestamp values in the AFSVol_TLV_value union. The 526 relative timestamp (time interval) contained within each vector 527 element shall be encoded using the rules specified in the AFS-3 528 time type specification [I-D.deason-afs3-type-time]. 530 AFSVOL_TLV_TYPE_VOL_ID = 13 532 This shall map to an afs_uint64 in the AFSVol_TLV_value union. 533 This field shall contain an AFS-3 volume identifier. When 534 transmitting 32-bit volume identifiers, the upper 32 bits of this 535 field MUST all be zeroes. 537 AFSVOL_TLV_TYPE_VOL_ID_VEC = 14 539 This shall map to an XDR variable length vector of up to 32768 540 afs_uint64 values in the AFSVol_TLV_value union. The elements 541 within this vector shall contain AFS-3 volume identifiers. When 542 transmitting 32-bit volume identifiers, the upper 32 bits of the 543 value MUST all be zeroes. 545 AFSVOL_TLV_TYPE_PART_ID = 15 547 This shall map to an afs_uint64 in the AFSVol_TLV_value union. 548 This field shall contain an AFS-3 vice partition identifier. 549 When transmitting 32-bit partition identifiers, the upper 32 bits 550 of this field MUST all be zeroes. 552 AFSVOL_TLV_TYPE_PART_ID_VEC = 16 554 This shall map to an XDR variable length vector of up to 32768 555 afs_uint64 values in the AFSVol_TLV_value union. The elements 556 within this vector shall contain AFS-3 vice partition 557 identifiers. When transmitting 32-bit partition identifiers, the 558 upper 32 bits of the value MUST all be zeroes. 560 AFSVOL_TLV_TYPE_DISK_BLOCKS = 17 562 This shall map to an afs_uint64 in the AFSVol_TLV_value union. 563 This field shall contain an unsigned integer count in units of 564 (1024 octet) disk blocks. 566 AFSVOL_TLV_TYPE_STAT_COUNTER = 18 568 This shall map to an afs_uint64 in the AFSVol_TLV_value union. 569 This field shall contain an unsigned integer counter statistic. 571 AFSVOL_TLV_TYPE_STAT_GAUGE = 19 573 This shall map to an afs_int64 in the AFSVol_TLV_value union. 574 This field shall contain a signed integer gauge (level) 575 statistic. 577 AFSVOL_TLV_TYPE_BIT64 = 20 579 This shall map to an afs_uint64 in the AFSVol_TLV_value union. 580 This field shall contain a 64-bit bit field. 582 AFSVOL_TLV_TYPE_VOL_DOW_USE = 21 584 This shall map to an type AFSVol_stat_use_per_dow, as defined in 585 Section 6.4. 587 AFSVOL_TLV_TYPE_OPAQUE = 22 589 This shall map to an XDR opaque byte array of maximum length 590 262144. The semantics and encoding of this field are defined by 591 the tag (please see Section 4.1.3 for further discussion). 593 4.1.2. TLV Flags 595 The AFSVol_TLV structure contains a 32-bit flags field for 596 communication of various ancillary boolean values. This memo defines 597 and allocates the following flag bits: 599 AFSVOL_TLV_FLAG_UNSUPPORTED = 0x1 601 When this flag is asserted, it tells the RPC caller that this tag 602 is not supported by this server. 604 AFSVOL_TLV_FLAG_READ_ERROR = 0x2 606 When this flag is asserted, it tells the RPC caller that the 607 server was unable to read a value for this tag, despite the tag 608 being supported by the server. 610 AFSVOL_TLV_FLAG_CRITICAL = 0x4 612 When this flag is asserted, it informs the peer that failure to 613 decode the payload associated with this tag is a fatal error that 614 should result in aborting this RPC call. 616 AFSVOL_TLV_FLAG_QUALIFIER_NO_MATCH = 0x8 618 When this flag is asserted, it informs the caller that the 619 qualifier passed in did not match any record. 621 AFSVOL_TLV_FLAG_MORE = 0x10 623 When this flag is asserted, it informs the caller that the server 624 was unable to send all available tags because the 625 AFSVOL_TLV_TAG_MAX XDR vector length limit was exceeded. 627 AFSVOL_TLV_FLAG_OBJ_NOT_SUPP = 0x20 629 When this flag is asserted, it tells the RPC caller that the 630 object in question does not support this specific tag, despite 631 the tag generally being supported by the server. An example of 632 this scenario could be a volume object which was created using a 633 format too old to support new metadata fields. 635 4.1.3. Use of AFSVOL_TLV_TYPE_OPAQUE 637 When possible, future protocol augmentations requiring the definition 638 of new data types should request allocation of a new standards-track 639 payload type code. Allocation of a type code should coincide with 640 standardization of the payload encoding associated with the type code 641 allocation. However, in limited circumstances where: 643 1. it is known a priori that there will never be any encoding 644 ambiguity (i.e., the opaque type for this tag shall map to 645 exactly one XDR type), and 647 2. the cost of type code allocation and encoding standardization are 648 deemed too high 650 use of the type code AFSVOL_TLV_TYPE_OPAQUE may be an acceptable 651 alternative. 653 4.2. Qualifiers 655 In some cases the value associated with a tag will be large, 656 structured data. A qualifier is a tag-specific parameter which 657 allows a caller to address a subset of the value stored in a tag. 658 For TLV get interfaces, specifying a qualifer can reduce the amount 659 of data sent over the wire. For TLV set interfaces, specifying a 660 qualifier permits a client to modify a subset of a structured value 661 without endangering cache coherence. Qualifiers are marshalled over 662 the wire as type AFSVol_TLV_value. Unless otherwise noted, it should 663 be assumed that a tag only supports the null qualifier (ext-union 664 discriminator set to AFSVOL_TLV_TYPE_NULL). The null qualifier 665 always references the entire value for a given tag. 667 5. AFSVol TLV Interface 669 5.1. Error Codes 671 A collection of new wire error codes are a required substrate. The 672 following new error codes are defined: 674 VOLSER_TAG_UNSUPPORTED 676 This server implementation does not support this tag. 678 VOLSER_TAG_READ_ONLY 680 This tag is marked read-only, and thus AFSVolSetVolumeTLV cannot 681 be invoked. 683 VOLSER_TAG_WRITE_FAILED 685 AFSVolSetVolumeTLV failed to write to this tag for an unspecified 686 reason. 688 VOLSER_TAG_DECODE_FAILED 690 AFSVolSetVolumeTLV could not set the value passed for this tag 691 because the AFSVol_TLV_value ext-union decoder raised an error 692 flag. This error may also be returned if, e.g., the XDR type 693 includes opaque data, then failure to validate the octet stream 694 embedded within the opaque would also result in this error code. 696 VOLSER_TAG_UNSUPPORTED_ENCODING 698 The discriminant passed in AFSVol_TLV_value to AFSVolSetVolumeTLV 699 is not supported by this implementation for this particular tag 700 (e.g., an AFSVOL_TLV_TYPE_OPAQUE value was passed to a tag which 701 only supports AFSVOL_TLV_TYPE_UINT64). 703 VOLSER_TLV_QUALIFIER_DECODE_FAILED 705 A qualifier could not be decoded because an AFSVol_TLV_value ext- 706 union decoder raised an error flag. This error may also be 707 returned if, e.g., the XDR type includes opaque data, then 708 failure to validate the octet stream embedded within the opaque 709 would also result in this error code. 711 VOLSER_TLV_QUALIFIER_UNSUPPORTED_ENCODING 713 The discriminant passed in AFSVol_TLV_value in the qualifier is 714 not supported by this implementation for this particular tag 715 (e.g., an AFSVOL_TLV_TYPE_OPAQUE value was passed as the 716 qualifier to a tag which only supports qualifiers of type 717 AFSVOL_TLV_TYPE_UINT64). 719 VOLSER_TLV_QUALIFIER_INVALID 721 The qualifier passed to the RPC was successfully decoded, and was 722 of a supported type, however the value of the qualifier failed 723 application-layer sanity checks. 725 VOLSER_TRANS_INVALID 727 An RPC failed to execute because the transaction ID passed as an 728 IN parameter was invalid. 730 5.2. Tag Introspection 732 In order for clients to determine which tags are supported by a given 733 server, an RPC is provided for obtaining the list of tags. In 734 addition to returning the tags, this RPC also returns a tag namespace 735 version (TSV) ordinal that can be used by clients to determine 736 whether a consistent set of tags was fetched from the server. 737 Additionally, this version ordinal can be compared against the value 738 returned by all other TLV RPC calls to determine whether the tag 739 cache remains coherent. The Rx procedure specification for the tag 740 enumeration RPC is as follows: 742 typedef afs_uint64 AFSVol_TLV_TSV; 743 typedef AFSVol_TLV_tag AFSVol_TLV_tag_vec; 745 proc GetVolumeTLVTags( 746 IN AFSVol_TLV_tag offset, 747 OUT AFSVol_TLV_tag_vec * tags, 748 OUT AFSVol_TLV_TSV * tsv 749 ) = XXX; 751 Figure 2 753 A compliant implementation MUST implement this RPC. The call 754 parameters are defined as follows: 756 offset 758 The offset IN parameter specifies the numeric offset of the first 759 tag to return. A value of zero indicates that the client wants 760 to start the enumeration at the beginning of the tag list. 762 tags 764 The tags OUT parameter contains a sorted list of supported tags, 765 beginning with the first supported tag greater than or equal to 766 the offset IN parameter. 768 tsv 770 The tsv OUT parameter contains the current server tag namespace 771 version ordinal. When this value changes from the previously- 772 seen value on the client, it indicates that tag namespace cache 773 coherence has been lost, and the client SHOULD restart fetching 774 the tag namespace from offset zero. 776 5.2.1. Tag Namespace Cache Coherence 778 Because the AFSVol interface is stateless, cache coherence cannot be 779 maintained via the normal AFS mechanism. Thus, AFSVol clients MUST 780 treat enumerated tags as ephemeral with a TTL of two hours. 782 The Tag nameSpace Version (TSV) ordinal is used to communicate the 783 current version of the tag namespace to the caller. Version zero is 784 a reserved value, so the server must initialize this verion ordinal 785 to a value great than 1. Servers MUST ensure that version ordinals 786 are unique within any 2 hour TTL period. 788 5.3. TLV Get 790 The Rx procedure specification for the TLV get interface will be as 791 follows: 793 struct AFSVol_TLV_query { 794 AFSVol_TLV_tag tq_tag; 795 AFSVol_TLV_value tq_qualifier; 796 }; 798 typedef AFSVol_TLV_query AFSVol_TLV_query_vec; 799 typedef AFSVol_TLV AFSVol_TLV_vec; 801 proc GetOneVolumeTLV( 802 IN afs_uint64 partId, 803 IN afs_uint64 volId, 804 IN AFSVol_TLV_query_vec * queries, 805 OUT AFSVol_TLV_vec * tuples, 806 OUT AFSVol_TLV_TSV * tsv 807 ) = XXX; 809 Figure 3 811 A compliant implementation MUST implement this RPC. The call 812 parameters are defined as follows: 814 partId 816 The partId IN parameter specifies the disk partition on which the 817 volume is located. 819 volId 821 The volId IN parameter specifies the volume for which TLV tuples 822 are being requested. 824 queries 826 The queries IN parameter specifies an optional list of tags for 827 which TLV tuples are desired. If this parameter is zero-length, 828 then the server will return up to AFSVOL_TLV_TAG_MAX TLV tuples. 829 If an unknown tag identifier is passed in the tags parameter, 830 then the server will return a tuple with the 831 AFSVOL_TLV_FLAG_UNSUPPORTED bit asserted in AFSVol_TLV.tlv_flags, 832 and the tlv type set to AFSVOL_TLV_TYPE_NULL. If the volume 833 object in question does not support a given metadata tag, then a 834 tuple will be returned with AFSVOL_TLV_FLAG_OBJ_NOT_SUPP set in 835 the AFSVol_TLV.tlv_flags field, and the tlv type set to 836 AFSVOL_TLV_TYPE_NULL. Similarly, if the server is unable to 837 retrieve the value for a supported tag, then a tuple will be 838 returned with AFSVOL_TLV_FLAG_READ_ERROR set in the 839 AFSVol_TLV.tlv_flags field, and the tlv type set to 840 AFSVOL_TLV_TYPE_NULL. The AFSVol_TLV_query.tq_qualifier field 841 contains optional tag-specific qualifiers which would allow the 842 implementation to return a subset of the data for a specific tag. 843 When a non-NULL qualifier is passed, and the qualifier fails to 844 match any record, then the flag bit 845 AFSVOL_TLV_FLAG_QUALIFIER_NO_MATCH will be set in 846 AFSVol_TLV.tlv_flags field, and the tlv type set to 847 AFSVOL_TLV_TYPE_NULL. 849 tuples 851 The tuples OUT parameter contains up to AFSVOL_TLV_TAG_MAX TLV 852 tuples for this volume. If all tags cannot be sent due to 853 AFSVOL_TLV_TAG_MAX vector length limit, then the flag bit 854 AFSVOL_TLV_FLAG_MORE SHALL be asserted in the last element. 856 tsv 858 The tsv OUT parameter contains the current server tag namespace 859 version ordinal. When this value changes from the previously- 860 seen value on the client, it indicates that tag namespace cache 861 coherence has been lost, and the client SHOULD use 862 AFSVolGetVolumeTLVTags (see Figure 2) to re-fetch the tag 863 namespace. 865 5.4. TLV Streaming Get 867 This call is similar to the call described in the previous section, 868 with the exception that TLV tuples will be returned for multiple 869 volumes at once using an Rx split call interface. The Rx procedure 870 specification is as follows: 872 const AFSVOL_BULK_GETVOLUME_MAX = 1024; 874 typedef afs_uint64 AFSVol_TLV_part_id_vec; 875 typedef afs_uint64 AFSVol_TLV_vol_id_vec; 877 struct AFSVol_TLV_vol_list { 878 afs_uint64 partId; 879 AFSVol_TLV_Vol_id_vec * volIds; 880 }; 882 typedef struct AFSVol_TLV_vol_list 883 AFSVol_TLV_get_filter; 885 proc GetVolumesTLV( 886 IN AFSVol_TLV_get_filter * filter, 887 IN AFSVol_TLV_query_vec * queries, 888 OUT AFSVol_TLV_TSV * tsv 889 ) split = XXX; 891 Figure 4 893 Implementation of this RPC is OPTIONAL. The call parameters are 894 defined as follows: 896 filter 898 The filter IN parameter specifies an optional list of vice 899 partitions and volume identifiers. If the filter vector is zero- 900 length, then TLV information is requested for all volumes on all 901 vice partitions. If this list is non-zero in length, then TLV 902 information is requested only for volumes on specific vice 903 partitions. Furthermore, if the volIds vector in a specific 904 filter vector index is non-zero in length, then TLV information 905 is only returned for thoese volumes whose identifiers are 906 enumerated in the volIds vector. 908 queries 910 The queries IN parameter specifies an optional list of tags for 911 which TLV tuples are desired. If this parameter is zero-length, 912 then the server will return up to AFSVOL_TLV_TAG_MAX TLV tuples. 913 If an unknown tag identifier is passed in the tags parameter, 914 then the server will return a tuple with the 915 AFSVOL_TLV_FLAG_UNSUPPORTED bit asserted in AFSVol_TLV.tlv_flags, 916 and the tlv type set to AFSVOL_TLV_TYPE_NULL. If the volume 917 object in question does not support a given metadata tag, then a 918 tuple will be returned with AFSVOL_TLV_FLAG_OBJ_NOT_SUPP set in 919 the AFSVol_TLV.tlv_flags field, and the tlv type set to 920 AFSVOL_TLV_TYPE_NULL. Similarly, if the server is unable to 921 retrieve the value for a supported tag, then a tuple will be 922 returned with AFSVOL_TLV_FLAG_READ_ERROR set in the 923 AFSVol_TLV.tlv_flags field, and the tlv type set to 924 AFSVOL_TLV_TYPE_NULL. The AFSVol_TLV_query.tq_qualifier field 925 contains optional tag-specific qualifiers which would allow the 926 implementation to return a subset of the data for a specific tag. 927 When a non-NULL qualifier is passed, and the qualifier fails to 928 match any record, then the flag bit 929 AFSVOL_TLV_FLAG_QUALIFIER_NO_MATCH will be set in 930 AFSVol_TLV.tlv_flags field, and the tlv type set to 931 AFSVOL_TLV_TYPE_NULL. 933 tsv 935 The tsv OUT parameter contains the current server tag namespace 936 version ordinal. When this value changes from the previously- 937 seen value on the client, it indicates that tag namespace cache 938 coherence has been lost, and the client SHOULD use 939 AFSVolGetVolumeTLVTags (see Figure 2) to re-fetch the tag 940 namespace. 942 5.4.1. Split call stream encoding 944 The contents of the split call stream shall be an xdrrec stream 945 containing a finite sequence of XDR-encoded AFSVol_TLV structures, 946 each of which shall be marked as a separate record (typically by 947 calling xdrrec_endofrecord). End of sequence will be annotated by a 948 dummy tuple containing the special tag type AFSVOL_TLV_TAG_EOS. 950 5.5. TLV Set 952 The Rx procedure specification for the TLV set interface will be as 953 follows: 955 struct AFSVol_TLV_store { 956 AFSVol_TLV ts_tuple; 957 AFSVol_TLV_value ts_qualifier; 958 }; 960 typedef AFSVol_TLV_store AFSVol_TLV_store_vec; 961 typedef afs_int32 AFSVol_TLV_result_vec; 963 proc SetVolumeTLV( 964 IN afs_int32 trans, 965 IN AFSVol_TLV_TSV assert_tsv, 966 IN AFSVol_TLV_store_vec * tuples, 967 OUT AFSVol_TLV_result_vec * results, 968 OUT AFSVol_TLV_TSV * server_tsv 969 ) = XXX; 971 Figure 5 973 Implementation of this RPC is OPTIONAL. The call parameters are 974 defined as follows: 976 trans 978 The trans IN parameter specifies the transaction ID returned by a 979 previous invocation of AFSVolTransCreate. 981 assert_tsv 983 The assert_tsv IN parameter contains the TSV ordinal expected by 984 the client. When this parameter is zero, it implies that the 985 client wants the values to be set, regardless of the current 986 server tag namespace version. However, if the value of this 987 parameter is non-zero, it MUST match the current server TSV. 988 When there is a TSV mismatch, the call MUST fail with error code 989 VOLSER_TAG_TSV_MISMATCH. 991 tuples 993 The tuples IN parameter contains the list of TLV tuples to be set 994 by the server. 996 results 998 The results OUT parameter contains a list of error codes, one per 999 tuple. These error codes provide specific information regarding 1000 the success/failure of each TLV set operation. Valid error codes 1001 include: 1003 * VOLSER_TAG_UNSUPPORTED 1005 * VOLSER_TAG_READ_ONLY 1007 * VOLSER_TAG_WRITE_FAILED 1009 * VOLSER_TAG_DECODE_FAILED 1011 * VOLSER_TAG_UNSUPPORTED_ENCODING 1013 * VOLSER_TAG_TSV_MISMATCH 1015 * VOLSER_TLV_QUALIFIER_UNSUPPORTED_ENCODING 1017 * VOLSER_TLV_QUALIFIER_DECODE_FAILED 1019 * VOLSER_TLV_QUALIFIER_INVALID 1021 * VOLSERFAILEDOP 1023 * VOLSERBAD_ACCESS 1025 * VOLSER_TRANS_INVALID 1027 server_tsv 1029 The tsv OUT parameter contains the current server tag namespace 1030 version ordinal. When this value changes from the previously- 1031 seen value on the client, it indicates that tag namespace cache 1032 coherence has been lost, and the client SHOULD use 1033 AFSVolGetVolumeTLVTags (see Figure 2) to re-fetch the tag 1034 namespace. 1036 5.5.1. Call preprocessing 1038 The SetVolumeTLV begins by scanning all elements within the tuples 1039 array. If any elements have the AFSVOL_TLV_FLAG_CRITICAL bit 1040 asserted in tuples[i].ts_tuple.ts_flags, then preprocessing of the 1041 tuple must occur. For each tuple with the critical bit set, several 1042 preprocessing validation steps will be taken. 1044 5.5.1.1. Verify tag is supported 1046 The tag stored in tuples[i].ts_tuple.tlv_tag is checked to ensure 1047 that the server supports it. In the event that the tag is not 1048 supported, then the corresponding array index in the results array 1049 will be set to VOLSER_TAG_UNSUPPORTED, and the RPC call abort at the 1050 conclusion of critical tuple preprocessing with error code 1051 VOLSERFAILEDOP. 1053 5.5.1.2. Verify tag is writeable 1055 The tag stored in tuples[i].ts_tuple.tlv_flag is checked to ensure 1056 that it is a writeable property. In the event that the tag is read- 1057 only, then the corresponding array index in the results array will be 1058 set to VOLSER_TAG_READ_ONLY, and the RPC call will abort at the 1059 conclusion of critical tuple preprocessing with error code 1060 VOLSERFAILEDOP. 1062 5.5.1.3. Verify value encoding is supported 1064 The ext-union discriminator in tuples[i].ts_tuple.tlv_value is 1065 checked to make sure that it is a supported type. If the 1066 discriminator is not a supported type, then the corresponding array 1067 index in the results array will be set to 1068 VOLSER_TAG_UNSUPPORTED_ENCODING, and the RPC call will abort at the 1069 conclusion of critical tuple preprocessing with error code 1070 VOLSERFAILEDOP. 1072 5.5.1.4. Verify value can be decoded 1074 The value stored in tuples[i].ts_tuple.tlv_value is checked to make 1075 sure that it can be decoded. If the wire-encoded data cannot be 1076 decoded, then the corresponding array index in the results array will 1077 be set to VOLSER_TAG_DECODE_FAILED, and the RPC call will abort at 1078 the conclusion of critical tuple preprocessing with error code 1079 VOLSERFAILEDOP. 1081 5.5.1.5. Verify qualifier is supported 1083 Qualifiers are specific to a given tag. If for any reason the tag- 1084 specific validation logic determines that the qualifier is invalid, 1085 it may set the corresponding array index in the results array to one 1086 of VOLSER_TLV_QUALIFIER_UNSUPPORTED_ENCODING, 1087 VOLSER_TLV_QUALIFIER_DECODE_FAILED, or VOLSER_TLV_QUALIFIER_INVALID. 1088 As with the other validation steps, if a critical tuple fails 1089 qualifier validation, then the RPC call will abort at the conclusion 1090 of critical tuple preprocessing with error code VOLSERFAILEDOP. 1092 5.5.2. Call processing 1094 Once the necessary validation steps have been performed, the call 1095 will perform the set operations for each tuple. Errors encountered 1096 during the processing of each tuple will be recorded in the 1097 appropriate array index of the results array. At the conclusion the 1098 RPC will either return 0 if all set operations succeeded, or 1099 VOLSERFAILEDOP if any failed. 1101 6. Mapping of existing metadata onto TLV namespace 1103 Existing metadata available from several interfaces will also be 1104 exported as TLV tuples. This is being done not only for 1105 completeness, but also to prevent data races between 1106 AFSVolGetOneVolumeTLV, and the various legacy introspection 1107 interfaces. 1109 6.1. volintXInfo 1111 All metadata exported via the volintXInfo XDR structure will now be 1112 exported as TLV tuples. Unless otherwise specified, the values 1113 associated with each tag shall be identical to that returned for the 1114 associated field in volintXInfo by the AFSVolXListOneVolume 1115 interface. The following tuples will be allocated to export existing 1116 members of volintXInfo: 1118 AFSVOL_TLV_TAG_VOL_NAME 1120 This is the TLV analogue of volintXInfo.name. This tuple MUST 1121 have a payload of type AFSVOL_TLV_TYPE_STRING. The u_string 1122 payload field MUST contain a null-terminated string. 1124 AFSVOL_TLV_TAG_VOL_STATUS 1126 This is the TLV analogue of volintXInfo.status. This tuple MUST 1127 have payload of type AFSVOL_TLV_TYPE_UINT64. 1129 AFSVOL_TLV_TAG_VOL_IN_USE 1131 This is the TLV analogue of volintXInfo.inUse. This tuple will 1132 contain a boolean value, and therefore MUST have a payload type 1133 of either: AFSVOL_TLV_TYPE_TRUE, or AFSVOL_TLV_TYPE_FALSE. 1135 AFSVOL_TLV_TAG_VOL_ID 1137 This is the TLV analogue of volintXInfo.volid. This tuple MUST 1138 have a payload of type AFSVOL_TLV_TYPE_VOL_ID. 1140 AFSVOL_TLV_TAG_VOL_TYPE 1142 This is the TLV analogue of volintXInfo.type. This tuple MUST 1143 have a payload of type AFSVOL_TLV_TYPE_UINT64. 1145 AFSVOL_TLV_TAG_VOL_CLONE_ID 1147 This is the TLV analogue of volintXInfo.cloneID. This tuple MUST 1148 have a payload of type AFSVOL_TLV_TYPE_VOL_ID. 1150 AFSVOL_TLV_TAG_VOL_BACKUP_ID 1152 This is the TLV analogue of volintXInfo.backupID. This tuple 1153 MUST have a payload of type AFSVOL_TLV_TYPE_VOL_ID. 1155 AFSVOL_TLV_TAG_VOL_PARENT_ID 1157 This is the TLV analogue of volintXInfo.parentID. This tuple 1158 MUST have payload of type AFSVOL_TLV_TYPE_VOL_ID. 1160 AFSVOL_TLV_TAG_VOL_COPY_DATE 1162 This is the TLV analogue of volintXInfo.copyDate. This tuple 1163 MUST have payload of type AFSVOL_TLV_TYPE_TIME_ABS. 1165 AFSVOL_TLV_TAG_VOL_CREATE_DATE 1167 This is the TLV analogue of volintXInfo.creationDate. This tuple 1168 MUST have payload of type AFSVOL_TLV_TYPE_TIME_ABS. This 1169 timestamp shall be encoded using the rules specified in the AFS-3 1170 time type specification [I-D.deason-afs3-type-time]. 1172 AFSVOL_TLV_TAG_VOL_ACCESS_DATE 1174 This is the TLV analogue of volintXInfo.accessDate. This tuple 1175 MUST have payload of type AFSVOL_TLV_TYPE_TIME_ABS. This 1176 timestamp shall be encoded using the rules specified in the AFS-3 1177 time type specification [I-D.deason-afs3-type-time]. 1179 AFSVOL_TLV_TAG_VOL_UPDATE_DATE 1181 This is the TLV analogue of volintXInfo.updateDate. This tuple 1182 MUST have payload of type AFSVOL_TLV_TYPE_TIME_ABS. This 1183 timestamp shall be encoded using the rules specified in the AFS-3 1184 time type specification [I-D.deason-afs3-type-time]. 1186 AFSVOL_TLV_TAG_VOL_BACKUP_DATE 1188 This is the TLV analogue of volintXInfo.backupDate. This tuple 1189 MUST have payload of type AFSVOL_TLV_TYPE_TIME_ABS. This 1190 timestamp shall be encoded using the rules specified in the AFS-3 1191 time type specification [I-D.deason-afs3-type-time]. 1193 AFSVOL_TLV_TAG_VOL_SIZE 1195 This is the TLV analogue of volintXInfo.size. This tuple MUST 1196 have payload of type AFSVOL_TLV_TYPE_DISK_BLOCKS. 1198 AFSVOL_TLV_TAG_VOL_FILE_COUNT 1200 This is the TLV analogue of volintXInfo.filecount. This tuple 1201 MUST have payload of type AFSVOL_TLV_TYPE_STAT_GAUGE. 1203 AFSVOL_TLV_TAG_VOL_QUOTA_BLOCKS 1205 This is the TLV analogue of volintXInfo.maxquota. This tuple 1206 MUST have payload of type AFSVOL_TLV_TYPE_DISK_BLOCKS. 1208 AFSVOL_TLV_TAG_VOL_STAT_USE_TODAY 1210 This is the TLV analogue of volintXInfo.dayUse. This tuple MUST 1211 have payload of type AFSVOL_TLV_TYPE_STAT_COUNTER. This field 1212 tracks volume accesses by AFS-3 clients over the course of this 1213 calendar day, since midnight local time of the file server. 1215 Operational monitoring applications which need to correlate the 1216 start time for the counter against a date SHOULD simultaneously 1217 query the value of tag AFSVOL_TLV_TAG_VOL_STAT_USE_TODAY_DATE. 1218 For further discussion of the cache coherence implications, 1219 please see Section 6.4.2. 1221 It should be noted that the definition of an "access" is 1222 implementation-private, and thus comparison of access rates 1223 across AFS-3 implementations is not possible. 1225 AFSVOL_TLV_TAG_VOL_STAT_USE_PER_DOW 1227 This is the TLV exportation of the daily usage statistics for the 1228 past week. This tuple may have two different payload types, 1229 depending upon whether or not a qualifier is delivered. The 1230 payload and qualifier types will be discussed in Section 6.4. 1232 It should be noted that the definition of an "access" is 1233 implementation-private, and thus comparison of access rates 1234 across AFS-3 implementations is not possible. 1236 AFSVOL_TLV_TAG_VOL_STAT_READS 1238 This is the TLV analogue of volintXInfo.stat_reads. This tuple 1239 MUST have payload of type AFSVOL_TLV_TYPE_UINT64_VEC. This 1240 vector SHALL be of length 4. 1242 AFSVOL_TLV_TAG_VOL_STAT_WRITES 1244 This is the TLV analogue of volintXInfo.stat_reads. This tuple 1245 MUST have payload of type AFSVOL_TLV_TYPE_UINT64_VEC. This 1246 vector SHALL be of length 4. 1248 AFSVOL_TLV_TAG_VOL_STAT_FILE_SAME_AUTHOR 1250 This is the TLV analogue of volintXInfo.stat_fileSameAuthor. 1251 This tuple MUST have payload of type AFSVOL_TLV_TYPE_UINT64_VEC. 1252 This vector SHALL be of length 6. 1254 AFSVOL_TLV_TAG_VOL_STAT_FILE_DIFFERENT_AUTHOR 1256 This is the TLV analogue of volintXInfo.stat_fileDiffAuthor. 1257 This tuple MUST have payload of type AFSVOL_TLV_TYPE_UINT64_VEC. 1258 This vector SHALL be of length 6. 1260 AFSVOL_TLV_TAG_VOL_STAT_DIR_SAME_AUTHOR 1262 This is the TLV analogue of volintXInfo.stat_dirSameAuthor. This 1263 tuple MUST have payload of type AFSVOL_TLV_TYPE_UINT64_VEC. This 1264 vector SHALL be of length 6. 1266 AFSVOL_TLV_TAG_VOL_STAT_DIR_DIFFERENT_AUTHOR 1268 This is the TLV analogue of volintXInfo.stat_dirDiffAuthor. This 1269 tuple MUST have payload of type AFSVOL_TLV_TYPE_UINT64_VEC. This 1270 vector SHALL be of length 6. 1272 6.2. transDebugInfo 1274 All metadata exported via the transDebugInfo XDR structure will now 1275 be exported as TLV tuples. Unless otherwise specified, the values 1276 associated with each tag shall be identical to that returned for the 1277 associated field in transDebugInfo by the AFSVolMonitor interface. 1278 The following tuples will be allocated to export existing members of 1279 transDebugInfo: 1281 AFSVOL_TLV_TAG_VOL_TRANS_ID 1283 This is the TLV analogue of transDebugInfo.tid. This tuple MUST 1284 have payload of type AFSVOL_TLV_TYPE_UINT64. 1286 AFSVOL_TLV_TAG_VOL_TRANS_TIME 1288 This is the TLV analogue of transDebugInfo.time. This tuple MUST 1289 have payload of type AFSVOL_TLV_TYPE_TIME_REL. 1291 AFSVOL_TLV_TAG_VOL_TRANS_CREATE_TIME 1293 This is the TLV analogue of transDebugInfo.creationTime. This 1294 tuple MUST have payload of type AFSVOL_TLV_TYPE_TIME_ABS. 1296 AFSVOL_TLV_TAG_VOL_TRANS_RETURN_CODE 1298 This is the TLV analogue of transDebugInfo.returnCode. This 1299 tuple MUST have payload of type AFSVOL_TLV_TYPE_INT64. 1301 AFSVOL_TLV_TAG_VOL_TRANS_ATTACH_MODE 1303 This is the TLV analogue of transDebugInfo.iflags. This tuple 1304 MUST have payload of type AFSVOL_TLV_TYPE_BIT64. 1306 AFSVOL_TLV_TAG_VOL_TRANS_STATUS 1308 This is the TLV analogue of transDebugInfo.vflags This tuple MUST 1309 have payload of type AFSVOL_TLV_TYPE_BIT64. 1311 AFSVOL_TLV_TAG_VOL_TRANS_FLAGS 1313 This is the TLV analogue of transDebugInfo.tflags. This tuple 1314 MUST have payload of type AFSVOL_TLV_TYPE_BIT64. 1316 AFSVOL_TLV_TAG_VOL_TRANS_LAST_PROC_NAME 1318 This is the TLV analogue of transDebugInfo.lastProcName. This 1319 tuple MUST have payload of type AFSVOL_TLV_TYPE_STRING. The 1320 u_string payload field MUST contain a null-terminated string. 1322 AFSVOL_TLV_TAG_VOL_TRANS_CALL_VALID 1324 This is the TLV analogue of transDebugInfo.callValid. This tuple 1325 will contain a boolean value, and therefore MUST have a payload 1326 type of either: AFSVOL_TLV_TYPE_TRUE, or AFSVOL_TLV_TYPE_FALSE. 1328 AFSVOL_TLV_TAG_VOL_TRANS_READ_NEXT 1330 This is the TLV analogue of transDebugInfo.readNext. This tuple 1331 MUST have payload of type AFSVOL_TLV_TYPE_STAT_COUNTER. This 1332 field contains the next expected Rx data packet sequence number 1333 expected by the receive side of this transaction's bulk data 1334 transfer operation. 1336 AFSVOL_TLV_TAG_VOL_TRANS_XMIT_NEXT 1338 This is the TLV analogue of transDebugInfo.transmitNext. This 1339 tuple MUST have payload of type AFSVOL_TLV_TYPE_STAT_COUNTER. 1340 This field contains the next Rx data packet sequence number to be 1341 used by the transmit side of this transaction's bulk data 1342 transfer operation. 1344 AFSVOL_TLV_TAG_VOL_TRANS_LAST_RECV_TIME 1346 This is the TLV analogue of transDebugInfo.lastReceiveTime. This 1347 tuple MUST have payload of type AFSVOL_TLV_TYPE_TIME_ABS. 1349 AFSVOL_TLV_TAG_VOL_TRANS_LAST_SEND_TIME 1351 This is the TLV analogue of transDebugInfo.lastSendTime. This 1352 tuple MUST have payload of type AFSVOL_TLV_TYPE_TIME_ABS. 1354 6.3. Additional de facto-standardized fields 1356 Certain fields from the IBM AFS and OpenAFS file server's 1357 VolumeDiskData header are generally useful. In particular, several 1358 fields exported via the AFSVolGetFlags and AFSVolSetFlags RPCs should 1359 be exported via the TLV interface. The full list of supported TLV 1360 tuples are: 1362 AFSVOL_TLV_TAG_VOL_IN_SERVICE 1364 This tuple will contain a boolean value, and therefore MUST have 1365 a payload type of either: AFSVOL_TLV_TYPE_TRUE, or 1366 AFSVOL_TLV_TYPE_FALSE. When this bit is not asserted, the volume 1367 is administratively prohibited from coming online. 1369 AFSVOL_TLV_TAG_VOL_BLESSED 1371 This tuple will contain a boolean value, and therefore MUST have 1372 a payload type of either: AFSVOL_TLV_TYPE_TRUE, or 1373 AFSVOL_TLV_TYPE_FALSE. When this bit is not asserted, the volume 1374 is administratively prohibited from coming online. 1376 AFSVOL_TLV_TAG_VOL_RESTORED_FROM_ID 1378 This tuple MUST have payload of type AFSVOL_TLV_TYPE_VOL_ID. 1379 When this field is non-zero, it contains the volume ID contained 1380 in the dump from which it was restored. 1382 AFSVOL_TLV_TAG_VOL_DESTROYED 1384 This tuple will contain a boolean value, and therefore MUST have 1385 a payload type of either: AFSVOL_TLV_TYPE_TRUE, or 1386 AFSVOL_TLV_TYPE_FALSE. When this bit is asserted, this volume is 1387 flagged for deletion. 1389 AFSVOL_TLV_TAG_VOL_NEEDS_SALVAGE 1391 This tuple will contain a boolean value, and therefore MUST have 1392 a payload type of either: AFSVOL_TLV_TYPE_TRUE, or 1393 AFSVOL_TLV_TYPE_FALSE. When this bit is asserted, this volume 1394 requires a salvage. 1396 AFSVOL_TLV_TAG_VOL_OFFLINE_MESSAGE 1398 This tuple MUST have payload of type AFSVOL_TLV_TYPE_STRING. The 1399 u_string payload field MUST contain a null-terminated string. 1400 This field stores an administrative message to indicate why the 1401 volume is offline. 1403 AFSVOL_TLV_TAG_VOL_EXPIRATION_DATE 1405 This tuple MUST have payload of type AFSVOL_TLV_TYPE_TIME_ABS. 1406 This timestamp shall be encoded using the rules specified in the 1407 AFS-3 time type specification [I-D.deason-afs3-type-time]. To 1408 the best knowledge of the authors, this field is not standardized 1409 by any implementation. 1411 AFSVOL_TLV_TAG_VOL_QUOTA_RESERVATION 1413 This tuple MUST have payload of type AFSVOL_TLV_TYPE_DISK_BLOCKS. 1414 This field, otherwise known as minquota, specifies the amount of 1415 storage (in units of 1024 octets) that are reserved on the 1416 underlying storage for use by this volume. 1418 AFSVOL_TLV_TAG_VOL_STAT_USE_TODAY_DATE 1420 This tuple MUST have payload of type AFSVOL_TLV_TYPE_TIME_ABS. 1421 This field, otherwise known as dayUseDate, specifies the 1422 timestamp when AFSVOL_TLV_TAG_VOL_STAT_USE_TODAY was reset to 1423 zero, and the previous value rolled over to index 0 of 1424 AFSVOL_TLV_TAG_VOL_STAT_USE_PER_DOW. 1426 6.4. Day-of-week usage statistics 1428 The day-of-week usage statistics accessed via tag 1429 AFSVOL_TLV_TAG_VOL_STAT_USE_PER_DOW provide access to historic data 1430 for the 7 days prior to the current access counter available via tag 1431 AFSVOL_TLV_TAG_VOL_STAT_USE_TODAY. Depending on the desired mode of 1432 statistics collection, two qualifier types are supported by this tag. 1434 6.4.1. Qualifiers 1436 6.4.1.1. NULL qualifier 1438 When the qualifier is of type AFSVOL_TLV_TYPE_NULL, then a custom 1439 payload of type AFSVOL_TLV_TYPE_VOL_DOW_USE will be used to deliver 1440 day-of-week usage data for the past week. This type is defined as 1441 follows: 1443 struct AFSVol_stat_use_per_dow { 1444 afs_uint64 stat_dow[7]; 1445 afs_uint32 stat_flags; 1446 }; 1448 Figure 6 1450 Seven bits in the stat_flags field are used to assert data validity 1451 for each day of week. These bits are present to help monitoring 1452 applications distinguish between days for which no data was collected 1453 (e.g. due to the volume being less than eight days old) and days when 1454 there were exactly zero accesses. These bits are defined as follows: 1456 Flag Description 1457 ----- ----------- 1458 AFSVOL_VOL_STAT_DOW0_VALID stat_dow[0] is valid 1459 AFSVOL_VOL_STAT_DOW1_VALID stat_dow[1] is valid 1460 AFSVOL_VOL_STAT_DOW2_VALID stat_dow[2] is valid 1461 AFSVOL_VOL_STAT_DOW3_VALID stat_dow[3] is valid 1462 AFSVOL_VOL_STAT_DOW4_VALID stat_dow[4] is valid 1463 AFSVOL_VOL_STAT_DOW5_VALID stat_dow[5] is valid 1464 AFSVOL_VOL_STAT_DOW6_VALID stat_dow[6] is valid 1465 AFSVOL_VOL_STAT_DOW_FUZZY server incapable of guaranteeing validity 1467 Day-of-week statistics flags 1469 Server implementations which are incapable of distinguishing between 1470 days when there was no usage, and for which there is no data SHOULD 1471 make a best-effort to populate the 7 per-day bits, and MUST assert 1472 the 0x80 stat_flags bit. 1474 6.4.1.2. UINT64 qualifier 1476 When the qualifier is of type AFSVOL_TLV_TYPE_UINT64, then a payload 1477 of type AFSVOL_TLV_TYPE_UINT64 will be used to deliver day-of-week 1478 usage data for the day of week specified in the uint64 qualifier. 1479 Valid qualifiers are in the range 0 to 6, where 0 means the day prior 1480 to the current day, and 6 means 7 days prior to the current day. 1482 6.4.2. Calendar day correlation 1484 Clients who need to poll AFSVOL_TLV_TAG_VOL_STAT_USE_TODAY or 1485 AFSVOL_TLV_TAG_VOL_STAT_USE_PER_DOW, and need to correlate this 1486 statistical data with specific calendar days SHOULD simultaneously 1487 query for the value stored at tag 1488 AFSVOL_TLV_TAG_VOL_STAT_USE_TODAY_DATE. By querying these tags in 1489 the same RPC invocation, the caller will be able correlate the usage 1490 statistics with calendar days in a race-free manner. Querying 1491 AFSVOL_TLV_TAG_VOL_STAT_USE_TODAY_DATE in a separate RPC invocation 1492 is not guarnteed to yield correct results, as there is no way to 1493 guarantee the value didn't change between the two RPC invocations. 1495 7. Extended volume state exportation 1497 In addition to exporting the existing volser state, DAFS state 1498 metadata will also be exported via the TLV interface. Specifically, 1499 an extended volume state field, and a raw DAFS state debugging tag, 1500 will be exported. 1502 7.1. Volume state explanations 1504 Given that volume state information is useful across all server 1505 implementations, a collection of generic state explanations shall be 1506 standardized. These standardized enumeration values shall be 1507 published via a special volume state explanation tag. The following 1508 states are initially defined in the namespace: 1510 AFSVOL_VOL_STATE_EXPL_NONE 1512 No further explanation is deemed necessary. 1514 AFSVOL_VOL_STATE_EXPL_UNKNOWN 1516 This volume is in its current state for unknown reasons. 1518 AFSVOL_VOL_STATE_EXPL_OUT_OF_SERVICE 1520 This volume is administratively out of service. For example, the 1521 IBM AFS and OpenAFS implementations both permit an administrator 1522 to force a volume offline by mutating the blessed or inService 1523 disk header bits. 1525 AFSVOL_VOL_STATE_EXPL_DELETED 1527 This volume no longer exists on-disk. This record merely serves 1528 as a pointer to tell clients that the volume has been permanently 1529 deleted, or moved to a new location. 1531 AFSVOL_VOL_STATE_EXPL_READY 1533 This volume is ready to service requests. If the primary volume 1534 state is offline, this means the volume is ready to be brought 1535 online as soon as a remote procedure call needs to access this 1536 volume. 1538 AFSVOL_VOL_STATE_EXPL_ATTACHING 1540 This volume is busy attaching. Assuming the process completes 1541 successfully, the volume will be brought online. 1543 AFSVOL_VOL_STATE_EXPL_DETACHING 1545 This volume is busy detaching. 1547 AFSVOL_VOL_STATE_EXPL_BUSY 1549 This volume is busy performing some ancillary operation which 1550 requires exclusive access. 1552 AFSVOL_VOL_STATE_EXPL_IO_BUSY 1554 This volume is busy performing an I/O operation which requires 1555 exclusive access. 1557 AFSVOL_VOL_STATE_EXPL_SALVAGING 1559 This volume is currently being salvaged in the background. 1561 AFSVOL_VOL_STATE_EXPL_SALVAGE_NEEDED 1563 This volume is offline, and will require a salvage before it can 1564 be brought online. 1566 AFSVOL_VOL_STATE_EXPL_ERROR 1568 This volume has been forced offline due to a non-recoverable 1569 error. Manual intervention by an administrator will be necessary 1570 to bring this volume back to an operable state. 1572 AFSVOL_VOL_STATE_EXPL_VOLUME_OPERATION 1574 This volume is currently offline because a volume transaction 1575 requires exclusive access. 1577 enum AFSVol_vol_state_expl { 1578 AFSVOL_VOL_STATE_EXPL_NONE = 0, 1579 AFSVOL_VOL_STATE_EXPL_UNKNOWN = 1, 1580 AFSVOL_VOL_STATE_EXPL_OUT_OF_SERVICE = 2, 1581 AFSVOL_VOL_STATE_EXPL_DELETED = 3, 1582 AFSVOL_VOL_STATE_EXPL_READY = 4, 1583 AFSVOL_VOL_STATE_EXPL_ATTACHING = 5, 1584 AFSVOL_VOL_STATE_EXPL_DETACHING = 6, 1585 AFSVOL_VOL_STATE_EXPL_BUSY = 7, 1586 AFSVOL_VOL_STATE_EXPL_IO_BUSY = 8, 1587 AFSVOL_VOL_STATE_EXPL_SALVAGING = 9, 1588 AFSVOL_VOL_STATE_EXPL_SALVAGE_NEEDED = 10, 1589 AFSVOL_VOL_STATE_EXPL_ERROR = 11, 1590 AFSVOL_VOL_STATE_EXPL_VOLUME_OPERATION = 12 1591 }; 1593 XDR definition of Volume State Enumeration 1595 7.2. Mapped process types 1597 It is useful to be able to track volume ownership by process type. 1598 In order to do this, a new program type namespace must be defined. 1599 The following types are initially defined in the program type 1600 namespace: 1602 AFSVOL_PROGRAM_TYPE_NONE 1604 This value refers to the absence of a process. 1606 AFSVOL_PROGRAM_TYPE_FILE_SERVER 1608 An afs file server process (Rx service ID 1). 1610 AFSVOL_PROGRAM_TYPE_VOLUME_SERVER 1612 An afs volume server process (Rx service ID 4). 1614 AFSVOL_PROGRAM_TYPE_SALVAGER 1616 An afs stand-alone salvager process. 1618 AFSVOL_PROGRAM_TYPE_SALVAGE_SERVER 1620 An OpenAFS DAFS salvage server process. 1622 AFSVOL_PROGRAM_TYPE_VOLUME_UTILITY 1624 Any ancillary stand-alone volume utility process. 1626 AFSVOL_PROGRAM_TYPE_UNKNOWN 1628 This value refers to an unknown process type. 1630 enum AFSVol_program_type { 1631 AFSVOL_PROGRAM_TYPE_NONE = 0, 1632 AFSVOL_PROGRAM_TYPE_FILE_SERVER = 1, 1633 AFSVOL_PROGRAM_TYPE_VOLUME_SERVER = 2, 1634 AFSVOL_PROGRAM_TYPE_SALVAGER = 3, 1635 AFSVOL_PROGRAM_TYPE_SALVAGE_SERVER = 4, 1636 AFSVOL_PROGRAM_TYPE_VOLUME_UTILITY = 5, 1637 AFSVOL_PROGRAM_TYPE_UNKNOWN = 6 1638 }; 1640 XDR definition of Program Type Enumeration 1642 7.3. TLV tuples 1644 Volume state will be exported via five new TLV tuples: 1646 AFSVOL_TLV_TAG_VOL_STATE_ONLINE 1648 This tuple MUST have payload of either type AFSVOL_TLV_TYPE_TRUE, 1649 or AFSVOL_TLV_TYPE_FALSE. This value SHALL tell the caller 1650 whether or not the volume is fully online. 1652 AFSVOL_TLV_TAG_VOL_STATE_AVAILABLE 1654 This tuple MUST have payload of either type AFSVOL_TLV_TYPE_TRUE, 1655 or AFSVOL_TLV_TYPE_FALSE. This tuple shall tell the caller 1656 whether or not the volume is available. This SHOULD be asserted 1657 either when the volume is fully online, or when the volume can be 1658 brought online on-demand within a reasonable length of time 1659 following receipt of an RPC call to Rx service id 1 requesting 1660 access to the volume. 1662 AFSVOL_TLV_TAG_VOL_STATE_EXPL 1664 This tuple MUST have payload of type AFSVOL_TLV_TYPE_UINT64. The 1665 u_u64 payload shall contain a volume state explanation 1666 enumeration value, as defined in Section 7.1. 1668 AFSVOL_TLV_TAG_VOL_STATE_DAFS_RAW 1670 For servers exporting capability AFSVOL_CAPABILITY_DAFS, this 1671 payload MUST be of type AFSVOL_TLV_TYPE_OPAQUE. Encoding of raw 1672 state is unspecified and implementation-private. 1674 AFSVOL_TLV_TAG_VOL_STATE_OWNING_PROCESS 1676 This tag should only be advertised as available on server 1677 implementations which support tracking volume ownership by 1678 process type. When available, this payload MUST be of type 1679 AFSVOL_TLV_TYPE_UINT64. The u_u64 payload shall contain a 1680 program type enumeration value, as defined in Section 7.2. 1682 8. AFS-3 Object Storage Extensions Policy Attributes 1684 RxOSD [AFS-OSD08] [AFS-OSD09] requires two TLV tuples to encode new 1685 quota types: 1687 AFSVOL_TLV_TAG_VOL_QUOTA_BLOCKS_STORED_LOCALLY 1689 The value in this tuple defines the maximum allowable storage, in 1690 units of blocks, that may be stored on the local file server 1691 partition. When storage is required beyond this limit, some data 1692 must be migrated to object storage devices (OSDs). This tuple 1693 MUST have a payload of type AFSVOL_TLV_TYPE_DISK_BLOCKS. 1695 AFSVOL_TLV_TAG_VOL_QUOTA_FILES 1697 The value in this tuple defines the maximum allowable file count 1698 for this volume. This tuple MUST have a payload of type 1699 AFSVOL_TLV_TYPE_UINT64. 1701 9. Backward Compatibility 1703 AFSVol services providing extended Tag-Length-Value RPCs MUST provide 1704 backwards compatible interfaces to both legacy clients and servers. 1705 Additionally, interoperability between TLV versions must also be 1706 specified if they do not comply with the following requirements: 1708 1. AFSVol TLV servers replying to legacy AFSVol clients MUST provide 1709 the identical response to an AFSVol server. 1711 2. AFSVol TLV clients communicating with AFSVol servers MUST fall 1712 back to using non-TLV AFSVol RPCs. 1714 3. AFSVol TLV clients to AFSVol TLV servers: 1716 A. Where capabilities match or the server can provide 1717 capabilities including those which the client requests, the 1718 server MUST reply with exactly the capabilities requested. 1720 B. Where the client requests capabilities that the server does 1721 not provide it MUST either return an 'unknown tag' error 1722 code, or (OPTIONAL) fall back to an non-TLV AFSVol response. 1724 10. Acknowledgements 1726 We would like to thank all of the participants at the 2009 Edinburgh 1727 AFS hackathon for their input into the design of this TLV mechanism. 1728 Alistair Ferguson has provided much useful feedback, especially with 1729 regard to backwards compatibility and discriminated union type 1730 identifier namespace allocations. Andrew Deason and Michael Meffie 1731 have provided considerable input with regard to the discriminated 1732 union XDR decoding problem, AFS registrar and namespace allocation 1733 concerns, what metadata should be exported in the initial revision, 1734 the notion of data qualifiers, as well as commentary about how they 1735 envision this extension being used to support future protocol 1736 extensions. Derrick Brashear has provided helpful feedback with 1737 regard to restructuring the volume state reporting tags. Thanks to 1738 Christof Hanke and Hartmut Reuter for collaborating to make this memo 1739 compatible with their RxOSD protocol enhancments, and, furthermore, 1740 for providing helpful feedback regarding the language in this draft. 1741 Finally, special thanks to Jeffrey Hutzelman for providing 1742 considerable help with restructuring this memo to improve readability 1743 and limit its scope to something tractable. 1745 11. IANA Considerations 1747 This memo includes no request to IANA. 1749 12. AFS Assign Numbers Registrar Considerations 1751 The AFS Assigned Numbers Registrar will need to consider several 1752 assigned numbers requests. 1754 12.1. Namespace allocations 1756 First and foremost, this memo requests that the AFS Registrar assume 1757 control over several new registries: 1759 1. AFSVol TLV payload type namespace 1761 2. AFSVol TLV tag namespace 1763 3. AFSVol TLV flag namespace 1765 4. AFSVol TLV Day-of-Week Stats flag namespace 1767 5. AFSVol Mapped Volume State namespace 1769 6. AFSVol Program Type namespace 1771 12.1.1. AFSVol TLV Payloads 1773 This memo requests the allocation of a new registry with the formal 1774 name "AFSVol TLV Payloads". This registry will be used to track 1775 allocations of enumeration values in the AFSVol_TLV_type XDR enum, 1776 and the mapping of these values onto their respective XDR type 1777 definitions. This is a 32-bit unsigned namespace. Allocations can 1778 fall into one of a few categories: 1780 Range Description 1781 ----- ----------- 1782 0 to 0xfeffffff - AFS-STDS Early Assignment 1783 0xff000000 - Private Assignment 1784 to 0xfffeffff 1785 0xffff0000 - reserved 1786 to 0xffffffff 1788 Subdivision into allocation policy regions 1790 In the table above, "AFS-STDS Early Assignment" refers to the 1791 allocation policy described in [I-D.wilkinson-afs3-standardisation]; 1792 "Private Assignment", and "Reserved" are as-described in [RFC5226]. 1794 Allocation requests for the "AFS-STDS Early Assignment" region MUST 1795 contain the following information: 1797 o type name 1799 o RFC section reference to definition of data encoding associated 1800 with this type enumeration value 1802 In addition, an "AFS-STDS Early Assignment" allocation request MAY 1803 include the following optional elements: 1805 o type description 1807 o desired value in AFSVol_TLV_type enumeration 1809 o RFC section reference to discussion regarding backwards 1810 compatibility 1812 o RFC section reference to relevant security considerations 1814 12.1.2. AFSVol TLV Tags 1816 This memo requests the allocation of a new registry with the formal 1817 name "AFSVol TLV Tags". This registry will be used to track 1818 allocations of enumeration values in the AFSVol_TLV_tag XDR enum, and 1819 the mapping of these values onto legal tags and qualifiers. This is 1820 a 32-bit unsigned namespace. Allocations can fall into one of a few 1821 categories: 1823 Range Description 1824 ----- ----------- 1825 0 to 0xfeffffff - AFS-STDS Early Assignment 1826 0xff000000 - Private Assignment 1827 to 0xfffeffff 1828 0xffff0000 - reserved 1829 to 0xffffffff 1831 Subdivision into allocation policy regions 1833 In the table above, "AFS-STDS Early Assignment" refers to the 1834 allocation policy described in [I-D.wilkinson-afs3-standardisation]; 1835 "Private Assignment", and "Reserved" are as-described in [RFC5226]. 1837 Allocation requests for the "AFS-STDS Early Assignment" region MUST 1838 contain the following information: 1840 o tag name 1842 o RFC section reference to definition of tag semantics 1844 In addition, an "AFS-STDS Early Assignment" allocation request MAY 1845 include the following optional elements: 1847 o tag description 1849 o desired value in AFSVol_TLV_tag enumeration 1851 o RFC section reference to definition of qualifier semantics for 1852 this tag 1854 o RFC section reference to discussion regarding backwards 1855 compatibility 1857 o RFC section reference to relevant security considerations 1859 12.1.3. AFSVol TLV Flags 1861 This memo requests the allocation of a new registry with the formal 1862 name "AFSVol TLV Flags". This registry will be used to track 1863 allocations of flag bits in the AFSVol_TLV.tlv_flags field. This is 1864 a 32-bit flag namespace. All flag bit allocations shall fall under 1865 the "AFS-STDS Early Assignment" allocation policy, as described in 1866 [I-D.wilkinson-afs3-standardisation]. Flag bit allocation requests 1867 MUST contain the following information: 1869 o flag name 1871 o RFC section reference to definition of flag semantics 1873 In addition, an allocation request MAY include the following optional 1874 elements: 1876 o flag description 1878 o desired flag bit value 1880 o RFC section reference to discussion regarding backwards 1881 compatibility 1883 o RFC section reference to relevant security considerations 1885 12.1.4. AFSVol DoW Stats Flags 1887 This memo requests the allocation of a new registry with the formal 1888 name "AFSVol DoW Stats Flags". This registry will be used to track 1889 allocations of flag bits in the AFSVol_stat_use_per_dow.stat_flags 1890 field. This is a 32-bit flag namespace. All flag bit allocations 1891 shall fall under the "AFS-STDS Early Assignment" allocation policy, 1892 as described in [I-D.wilkinson-afs3-standardisation]. Flag bit 1893 allocation requests MUST contain the following information: 1895 o flag name 1897 o RFC section reference to definition of flag semantics 1899 In addition, an allocation request MAY include the following optional 1900 elements: 1902 o flag description 1904 o desired flag bit value 1906 o RFC section reference to discussion regarding backwards 1907 compatibility 1909 o RFC section reference to relevant security considerations 1911 12.1.5. AFSVol Vol State Expls 1913 This memo requests the allocation of a new registry with the formal 1914 name "AFSVol Vol State Expls". This registry will be used to track 1915 allocations of enumeration values in the AFSVol_vol_state_expl enum 1916 (see Section 7.1). This is a 32-bit unsigned namespace. Allocations 1917 can fall into one of a few categories: 1919 Range Description 1920 ----- ----------- 1921 0 to 0xfeffffff - AFS-STDS Early Assignment 1922 0xff000000 - Private Assignment 1923 to 0xffffffff 1925 Subdivision into allocation policy regions 1927 In the table above, "AFS-STDS Early Assignment" refers to the 1928 allocation policy described in [I-D.wilkinson-afs3-standardisation]; 1929 "Private Assignment" is as-described in [RFC5226]. 1931 Allocation requests for the "AFS-STDS Early Assignment" region MUST 1932 contain the following information: 1934 o state name 1936 o RFC section reference to definition of this volume state 1937 enumeration value 1939 In addition, an "AFS-STDS Early Assignment" allocation request MAY 1940 include the following optional elements: 1942 o state description 1944 o desired value in AFSVol_vol_state_expl enumeration 1946 o RFC section reference to discussion regarding backwards 1947 compatibility 1949 o RFC section reference to relevant security considerations 1951 12.1.6. AFSVol Program Types 1953 This memo requests the allocation of a new registry with the formal 1954 name "AFSVol Program Types". This registry will be used to track 1955 allocations of enumeration values in the AFSVol_program_type enum 1956 (see Section 7.2). This is a 32-bit unsigned namespace. Allocations 1957 can fall into one of a few categories: 1959 Range Description 1960 ----- ----------- 1961 0 to 0xfeffffff - AFS-STDS Early Assignment 1962 0xff000000 - Private Assignment 1963 to 0xffffffff 1965 Subdivision into allocation policy regions 1967 In the table above, "AFS-STDS Early Assignment" refers to the 1968 allocation policy described in [I-D.wilkinson-afs3-standardisation]; 1969 "Private Assignment" is as-described in [RFC5226]. 1971 Allocation requests for the "AFS-STDS Early Assignment" region MUST 1972 contain the following information: 1974 o program name 1976 o RFC section reference to definition of this program type 1977 enumeration value 1979 In addition, an "AFS-STDS Early Assignment" allocation request MAY 1980 include the following optional elements: 1982 o program description 1984 o desired value in AFSVol_program_type enumeration 1986 o RFC section reference to discussion regarding backwards 1987 compatibility 1989 o RFC section reference to relevant security considerations 1991 12.2. Assigned numbers allocations 1993 In addition to requesting the allocation of new registries, this memo 1994 also requests several new allocations within existing assigned 1995 numbers registries. 1997 12.2.1. VICED Capability bits 1999 One new capability bit is requested: 2001 o VICED_CAPABILITY_DAFS (see Section 3) 2003 12.2.2. AFSVol Capabilities 2005 The following allocations are requested in the "AFSVol Capabilites" 2006 registry [I-D.keiser-afs3-capabilities]: 2008 o AFSVOL_CAPABILITY_DAFS = 0x1 (see Section 3) 2010 o AFSVOL_CAPABILITY_TLV = 0x2 (see Section 3) 2012 12.2.3. AFSVol TLV Payloads 2014 The following initial allocations are requested in the newly-created 2015 registry "AFSVol TLV Payloads": 2017 o AFSVOL_TLV_TYPE_NULL = 0 (see Section 4.1.1) 2019 o AFSVOL_TLV_TYPE_TRUE = 1 (see Section 4.1.1) 2021 o AFSVOL_TLV_TYPE_FALSE = 2 (see Section 4.1.1) 2023 o AFSVOL_TLV_TYPE_UINT64 = 3 (see Section 4.1.1) 2025 o AFSVOL_TLV_TYPE_UINT64_VEC = 4 (see Section 4.1.1) 2026 o AFSVOL_TLV_TYPE_INT64 = 5 (see Section 4.1.1) 2028 o AFSVOL_TLV_TYPE_INT64_VEC = 6 (see Section 4.1.1) 2030 o AFSVOL_TLV_TYPE_UUID = 7 (see Section 4.1.1) 2032 o AFSVOL_TLV_TYPE_STRING = 8 (see Section 4.1.1) 2034 o AFSVOL_TLV_TYPE_TIME_ABS = 9 (see Section 4.1.1) 2036 o AFSVOL_TLV_TYPE_TIME_ABS_VEC = 10 (see Section 4.1.1) 2038 o AFSVOL_TLV_TYPE_TIME_REL = 11 (see Section 4.1.1) 2040 o AFSVOL_TLV_TYPE_TIME_REL_VEC = 12 (see Section 4.1.1) 2042 o AFSVOL_TLV_TYPE_VOL_ID = 13 (see Section 4.1.1) 2044 o AFSVOL_TLV_TYPE_VOL_ID_VEC = 14 (see Section 4.1.1) 2046 o AFSVOL_TLV_TYPE_PART_ID = 15 (see Section 4.1.1) 2048 o AFSVOL_TLV_TYPE_PART_ID_VEC = 16 (see Section 4.1.1) 2050 o AFSVOL_TLV_TYPE_DISK_BLOCKS = 17 (see Section 4.1.1) 2052 o AFSVOL_TLV_TYPE_STAT_COUNTER = 18 (see Section 4.1.1) 2054 o AFSVOL_TLV_TYPE_STAT_GAUGE = 19 (see Section 4.1.1) 2056 o AFSVOL_TLV_TYPE_BIT64 = 20 (see Section 4.1.1) 2058 o AFSVOL_TLV_TYPE_VOL_DOW_USE = 21 (see Section 4.1.1) 2060 o AFSVOL_TLV_TYPE_OPAQUE = 22 (see Section 4.1.1) 2062 12.2.4. AFSVol TLV Tags 2064 The following initial allocations are requested in the newly-created 2065 registry "AFSVol TLV Tags": 2067 o AFSVOL_TLV_TAG_EOS = 0 (see Section 5.4.1) 2069 o AFSVOL_TLV_TAG_VOL_NAME = 1 (see Section 6.1) 2071 o AFSVOL_TLV_TAG_VOL_STATUS = 2 (see Section 6.1) 2072 o AFSVOL_TLV_TAG_VOL_IN_USE = 3 (see Section 6.1) 2074 o AFSVOL_TLV_TAG_VOL_ID = 4 (see Section 6.1) 2076 o AFSVOL_TLV_TAG_VOL_TYPE = 5 (see Section 6.1) 2078 o AFSVOL_TLV_TAG_VOL_CLONE_ID = 6 (see Section 6.1) 2080 o AFSVOL_TLV_TAG_VOL_BACKUP_ID = 7 (see Section 6.1) 2082 o AFSVOL_TLV_TAG_VOL_PARENT_ID = 8 (see Section 6.1) 2084 o AFSVOL_TLV_TAG_VOL_COPY_DATE = 9 (see Section 6.1) 2086 o AFSVOL_TLV_TAG_VOL_CREATE_DATE = 10 (see Section 6.1) 2088 o AFSVOL_TLV_TAG_VOL_ACCESS_DATE = 11 (see Section 6.1) 2090 o AFSVOL_TLV_TAG_VOL_UPDATE_DATE = 12 (see Section 6.1) 2092 o AFSVOL_TLV_TAG_VOL_BACKUP_DATE = 13 (see Section 6.1) 2094 o AFSVOL_TLV_TAG_VOL_SIZE = 14 (see Section 6.1) 2096 o AFSVOL_TLV_TAG_VOL_FILE_COUNT = 15 (see Section 6.1) 2098 o AFSVOL_TLV_TAG_VOL_QUOTA_BLOCKS = 16 (see Section 6.1) 2100 o AFSVOL_TLV_TAG_VOL_STAT_USE_TODAY = 17 (see Section 6.1) 2102 o AFSVOL_TLV_TAG_VOL_STAT_USE_PER_DOW = 18 (see Section 6.1) 2104 o AFSVOL_TLV_TAG_VOL_STAT_READS = 19 (see Section 6.1) 2106 o AFSVOL_TLV_TAG_VOL_STAT_WRITES = 20 (see Section 6.1) 2108 o AFSVOL_TLV_TAG_VOL_STAT_FILE_SAME_AUTHOR = 21 (see Section 6.1) 2110 o AFSVOL_TLV_TAG_VOL_STAT_FILE_DIFFERENT_AUTHOR = 22 (see 2111 Section 6.1) 2113 o AFSVOL_TLV_TAG_VOL_STAT_DIR_SAME_AUTHOR = 23 (see Section 6.1) 2115 o AFSVOL_TLV_TAG_VOL_STAT_DIR_DIFFERENT_AUTHOR = 24 (see 2116 Section 6.1) 2118 o AFSVOL_TLV_TAG_VOL_TRANS_ID = 25 (see Section 6.2) 2119 o AFSVOL_TLV_TAG_VOL_TRANS_TIME = 26 (see Section 6.2) 2121 o AFSVOL_TLV_TAG_VOL_TRANS_CREATE_TIME = 27 (see Section 6.2) 2123 o AFSVOL_TLV_TAG_VOL_TRANS_RETURN_CODE = 28 (see Section 6.2) 2125 o AFSVOL_TLV_TAG_VOL_TRANS_ATTACH_MODE = 29 (see Section 6.2) 2127 o AFSVOL_TLV_TAG_VOL_TRANS_STATUS = 30 (see Section 6.2) 2129 o AFSVOL_TLV_TAG_VOL_TRANS_FLAGS = 31 (see Section 6.2) 2131 o AFSVOL_TLV_TAG_VOL_TRANS_LAST_PROC_NAME = 32 (see Section 6.2) 2133 o AFSVOL_TLV_TAG_VOL_TRANS_CALL_VALID = 33 (see Section 6.2) 2135 o AFSVOL_TLV_TAG_VOL_TRANS_READ_NEXT = 34 (see Section 6.2) 2137 o AFSVOL_TLV_TAG_VOL_TRANS_XMIT_NEXT = 35 (see Section 6.2) 2139 o AFSVOL_TLV_TAG_VOL_TRANS_LAST_RECV_TIME = 36 (see Section 6.2) 2141 o AFSVOL_TLV_TAG_VOL_TRANS_LAST_SEND_TIME = 37 (see Section 6.2) 2143 o AFSVOL_TLV_TAG_VOL_IN_SERVICE = 38 (see Section 6.3) 2145 o AFSVOL_TLV_TAG_VOL_BLESSED = 39 (see Section 6.3) 2147 o AFSVOL_TLV_TAG_VOL_RESTORED_FROM_ID = 40 (see Section 6.3) 2149 o AFSVOL_TLV_TAG_VOL_DESTROYED = 41 (see Section 6.3) 2151 o AFSVOL_TLV_TAG_VOL_NEEDS_SALVAGE = 42 (see Section 6.3) 2153 o AFSVOL_TLV_TAG_VOL_OFFLINE_MESSAGE = 43 (see Section 6.3) 2155 o AFSVOL_TLV_TAG_VOL_EXPIRATION_DATE = 44 (see Section 6.3) 2157 o AFSVOL_TLV_TAG_VOL_QUOTA_RESERVATION = 45 (see Section 6.3) 2159 o AFSVOL_TLV_TAG_VOL_STAT_USE_TODAY_DATE = 46 (see Section 6.3) 2161 o AFSVOL_TLV_TAG_VOL_STATE_ONLINE = 47 (see Section 7) 2163 o AFSVOL_TLV_TAG_VOL_STATE_AVAILABLE = 48 (see Section 7) 2165 o AFSVOL_TLV_TAG_VOL_STATE_EXPL = 49 (see Section 7) 2166 o AFSVOL_TLV_TAG_VOL_STATE_DAFS_RAW = 50 (see Section 7) 2168 o AFSVOL_TLV_TAG_VOL_STATE_OWNING_PROCESS = 51 (see Section 7) 2170 o AFSVOL_TLV_TAG_VOL_QUOTA_BLOCKS_STORED_LOCALLY = 52 (see 2171 Section 8) 2173 o AFSVOL_TLV_TAG_VOL_QUOTA_FILES = 53 (see Section 8) 2175 12.2.5. AFSVol TLV Flags 2177 The following initial allocations are requested within the newly- 2178 created registry "AFSVol TLV Flags": 2180 o AFSVOL_TLV_FLAG_UNSUPPORTED = 0x1 (see Section 4.1.2) 2182 o AFSVOL_TLV_FLAG_READ_ERROR = 0x2 (see Section 4.1.2) 2184 o AFSVOL_TLV_FLAG_CRITICAL = 0x4 (see Section 4.1.2) 2186 o AFSVOL_TLV_FLAG_QUALIFIER_NO_MATCH = 0x8 (see Section 4.1.2) 2188 o AFSVOL_TLV_FLAG_MORE = 0x10 (see Section 4.1.2) 2190 o AFSVOL_TLV_FLAG_OBJ_NOT_SUPP = 0x20 (see Section 4.1.2) 2192 12.2.6. AFSVol DoW Stats Flags 2194 The following initial allocations are requested within the newly- 2195 created registry "AFSVol DoW Stats Flags": 2197 o AFSVOL_VOL_STAT_DOW0_VALID = 0x1 (see Section 6.4) 2199 o AFSVOL_VOL_STAT_DOW1_VALID = 0x2 (see Section 6.4) 2201 o AFSVOL_VOL_STAT_DOW2_VALID = 0x4 (see Section 6.4) 2203 o AFSVOL_VOL_STAT_DOW3_VALID = 0x8 (see Section 6.4) 2205 o AFSVOL_VOL_STAT_DOW4_VALID = 0x10 (see Section 6.4) 2207 o AFSVOL_VOL_STAT_DOW5_VALID = 0x20 (see Section 6.4) 2209 o AFSVOL_VOL_STAT_DOW6_VALID = 0x40 (see Section 6.4) 2211 o AFSVOL_VOL_STAT_DOW_FUZZY = 0x80 (see Section 6.4) 2213 12.2.7. VOLS Error Table 2215 Within the VOLS error table (offset 1492325120), several new codes 2216 need to be allocated: 2218 o VOLSER_TAG_UNSUPPORTED 2220 o VOLSER_TAG_READ_ONLY 2222 o VOLSER_TAG_WRITE_FAILED 2224 o VOLSER_TAG_DECODE_FAILED 2226 o VOLSER_TAG_UNSUPPORTED_ENCODING 2228 o VOLSER_TLV_QUALIFIER_UNSUPPORTED_ENCODING 2230 o VOLSER_TLV_QUALIFIER_DECODE_FAILED 2232 o VOLSER_TLV_QUALIFIER_INVALID 2234 o VOLSER_TRANS_INVALID 2236 12.2.8. AFSVol Vol State Expls 2238 The following initial allocations are requested within the newly- 2239 created registry "AFSVol Vol State Expls": 2241 o AFSVOL_VOL_STATE_EXPL_NONE = 0 (see Section 7.1) 2243 o AFSVOL_VOL_STATE_EXPL_UNKNOWN = 1 (see Section 7.1) 2245 o AFSVOL_VOL_STATE_EXPL_OUT_OF_SERVICE = 2 (see Section 7.1) 2247 o AFSVOL_VOL_STATE_EXPL_DELETED = 3 (see Section 7.1) 2249 o AFSVOL_VOL_STATE_EXPL_READY = 4 (see Section 7.1) 2251 o AFSVOL_VOL_STATE_EXPL_ATTACHING = 5 (see Section 7.1) 2253 o AFSVOL_VOL_STATE_EXPL_DETACHING = 6 (see Section 7.1) 2255 o AFSVOL_VOL_STATE_EXPL_BUSY = 7 (see Section 7.1) 2257 o AFSVOL_VOL_STATE_EXPL_IO_BUSY = 8 (see Section 7.1) 2259 o AFSVOL_VOL_STATE_EXPL_SALVAGING = 9 (see Section 7.1) 2260 o AFSVOL_VOL_STATE_EXPL_SALVAGE_NEEDED = 10 (see Section 7.1) 2262 o AFSVOL_VOL_STATE_EXPL_ERROR = 11 (see Section 7.1) 2264 o AFSVOL_VOL_STATE_EXPL_VOLUME_OPERATION = 12 (see Section 7.1) 2266 12.2.9. AFSVol Program Types 2268 Within the new AFS program type namespace, the following allocations 2269 are requested: 2271 o AFSVOL_PROGRAM_TYPE_NONE = 0 (see Section 7.2) 2273 o AFSVOL_PROGRAM_TYPE_FILE_SERVER = 1 (see Section 7.2) 2275 o AFSVOL_PROGRAM_TYPE_VOLUME_SERVER = 2 (see Section 7.2) 2277 o AFSVOL_PROGRAM_TYPE_SALVAGER = 3 (see Section 7.2) 2279 o AFSVOL_PROGRAM_TYPE_SALVAGE_SERVER = 4 (see Section 7.2) 2281 o AFSVOL_PROGRAM_TYPE_VOLUME_UTILITY = 5 (see Section 7.2) 2283 o AFSVOL_PROGRAM_TYPE_UNKNOWN = 6 (see Section 7.2) 2285 13. Security Considerations 2287 Security and authorization issues are tag-specific. Most known 2288 implementations of the legacy AFSVol RPCs permitted rxnull 2289 connections to perform the four ListVolume RPCs, and AFSVolMonitor. 2290 Arguably, it is time to re-evaluate this decision, and subsequently 2291 restrict access to some tags, as they do permit potentially sensitive 2292 volume--or operational--metadata to leak onto public networks. 2294 14. References 2296 14.1. Normative References 2298 [I-D.deason-afs3-type-time] 2299 Deason, A., "Base Types for Time in AFS-3", 2300 draft-deason-afs3-type-time-03 (work in progress), 2301 August 2011. 2303 [I-D.keiser-afs3-capabilities] 2304 Keiser, T., Jenkins, S., and A. Deason, "AFS-3 Protocol 2305 Capabilities Query Mechanism", 2306 draft-keiser-afs3-capabilities-00 (work in progress), 2307 September 2012. 2309 [I-D.keiser-afs3-xdr-primitive-types] 2310 Keiser, T. and A. Deason, "AFS-3 Rx RPC XDR Primitive Type 2311 Definitions", draft-keiser-afs3-xdr-primitive-types-01 2312 (work in progress), September 2012. 2314 [I-D.keiser-afs3-xdr-union] 2315 Keiser, T. and A. Deason, "Extensible XDR Discriminated 2316 Union Primitive Type", draft-keiser-afs3-xdr-union-06 2317 (work in progress), September 2012. 2319 [I-D.wilkinson-afs3-standardisation] 2320 Wilkinson, S., "Options for AFS Standardisation", 2321 draft-wilkinson-afs3-standardisation-00 (work in 2322 progress), June 2010. 2324 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2325 Requirement Levels", BCP 14, RFC 2119, March 1997. 2327 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2328 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2329 May 2008. 2331 14.2. Informative References 2333 [AFS-OSD08] 2334 Tobbicke, R., Maslennikov, A., Giammarino, L., Belloni, 2335 R., and H. Reuter, "AFS + Object Storage", AFS and 2336 Kerberos Best Practices Workshop 2008, May 2008, . 2340 [AFS-OSD09] 2341 Reuter, H., Frank, F., and A. Maslennikov, "Embedded 2342 Filesystems (Direct Client Access to Vice Partitions)", 2343 AFS and Kerberos Best Practices Workshop 2009, June 2009, 2344 . 2347 [AFS3-RX] Zayas, E., "AFS-3 Programmer's Reference: Specification 2348 for the Rx Remote Procedure Call Facility", Transarc Corp. 2349 Tech. Rep. FS-00-D164, August 1991. 2351 [AFS3-VVL] 2352 Zayas, E., "AFS-3 Programmer's Reference: Volume Server/ 2353 Volume Location Server Interface", Transarc Corp. Tech. 2355 Rep. FS-00-D165, August 1991. 2357 [CMU-ITC-83-025] 2358 Morris, J., Van Houweling, D., and K. Slack, "The 2359 Information Technology Center", CMU ITC Tech. Rep. CMU- 2360 ITC-83-025, 1983. 2362 [CMU-ITC-84-020] 2363 West, M., "VICE File System Services", CMU ITC Tech. 2364 Rep. CMU-ITC-84-020, August 1984. 2366 [CMU-ITC-85-039] 2367 Satyanarayanan, M., Howard, J., Nichols, D., Sidebotham, 2368 R., Spector, A., and M. West, "The ITC Distributed File 2369 System: Principles and Design", Proc. 10th ACM Symp. 2370 Operating Sys. Princ. Vol. 19, No. 5, December 1985. 2372 [CMU-ITC-87-068] 2373 Howard, J., Kazar, M., Menees, S., Nichols, D., 2374 Satyanarayanan, M., Sidebotham, R., and M. West, "Scale 2375 and Performance in a Distributed File System", ACM Trans. 2376 Comp. Sys. Vol. 6, No. 1, pp. 51-81, February 1988. 2378 [CMU-ITC-88-062] 2379 Howard, J., "An Overview of the Andrew File System"", 2380 Proc. 1988 USENIX Winter Tech. Conf. pp. 23-26, 2381 February 1988. 2383 [CMU-ITC-88-070] 2384 Zayas, E. and C. Everhart, "Design and Specification of 2385 the Cellular Andrew Environment", CMU ITC Tech. Rep. CMU- 2386 ITC-88-070, August 1988. 2388 [DAFS] Keiser, T., "Demand Attach / Fast-restart File Server", 2389 AFS and Kerberos Best Practices Workshop 2006, June 2006, 2390 . 2393 [RFC4506] Eisler, M., "XDR: External Data Representation Standard", 2394 STD 67, RFC 4506, May 2006. 2396 [RFC5531] Thurlow, R., "RPC: Remote Procedure Call Protocol 2397 Specification Version 2", RFC 5531, May 2009. 2399 Appendix A. Sample Rx RPC-L Definition for AFSVol TLV Mechanism 2401 const AFSVOL_TLV_TAG_MAX = 1024; /* upper-bound on number of 2402 * TLV tuples per RPC */ 2403 const AFSVOL_TLV_OPAQUE_MAX = 262144; /* upper-bound on size of 2404 * value payload */ 2405 const AFSVOL_TLV_UINT64_MAX = 32768; /* upper-bound on length of 2406 uint64 vector payload */ 2407 const AFSVOL_TLV_TIME_MAX = 21845; /* upper-bound on length of 2408 AFSTime vector payload */ 2409 const AFSVOL_BULK_GETVOLUME_MAX = 1024; /* upper-bound on 2410 * (partition, volume) 2411 * tuples per RPC */ 2413 const AFSVOL_TLV_FLAG_UNSUPPORTED = 0x1; 2414 const AFSVOL_TLV_FLAG_READ_ERROR = 0x2; 2415 const AFSVOL_TLV_FLAG_CRITICAL = 0x4; 2416 const AFSVOL_TLV_FLAG_QUALIFIER_NO_MATCH = 0x8; 2417 const AFSVOL_TLV_FLAG_MORE = 0x10; 2418 const AFSVOL_TLV_FLAG_OBJ_NOT_SUPP = 0x20; 2420 enum AFSVol_TLV_type { 2421 AFSVOL_TLV_TYPE_NULL = 0, 2422 AFSVOL_TLV_TYPE_TRUE = 1, 2423 AFSVOL_TLV_TYPE_FALSE = 2, 2424 AFSVOL_TLV_TYPE_UINT64 = 3, 2425 AFSVOL_TLV_TYPE_UINT64_VEC = 4, 2426 AFSVOL_TLV_TYPE_INT64 = 5, 2427 AFSVOL_TLV_TYPE_INT64_VEC = 6, 2428 AFSVOL_TLV_TYPE_UUID = 7, 2429 AFSVOL_TLV_TYPE_STRING = 8, 2430 AFSVOL_TLV_TYPE_TIME_ABS = 9, 2431 AFSVOL_TLV_TYPE_TIME_ABS_VEC = 10, 2432 AFSVOL_TLV_TYPE_TIME_REL = 11, 2433 AFSVOL_TLV_TYPE_TIME_REL_VEC = 12, 2434 AFSVOL_TLV_TYPE_VOL_ID = 13, 2435 AFSVOL_TLV_TYPE_VOL_ID_VEC = 14, 2436 AFSVOL_TLV_TYPE_PART_ID = 15, 2437 AFSVOL_TLV_TYPE_PART_ID_VEC = 16, 2438 AFSVOL_TLV_TYPE_DISK_BLOCKS = 17, 2439 AFSVOL_TLV_TYPE_STAT_COUNTER = 18, 2440 AFSVOL_TLV_TYPE_STAT_GAUGE = 19, 2441 AFSVOL_TLV_TYPE_BIT64 = 20, 2442 AFSVOL_TLV_TYPE_VOL_DOW_USE = 21, 2443 AFSVOL_TLV_TYPE_OPAQUE = 22 2444 }; 2446 const AFSVOL_VOL_STAT_DOW0_VALID = 0x1; 2447 const AFSVOL_VOL_STAT_DOW1_VALID = 0x2; 2448 const AFSVOL_VOL_STAT_DOW2_VALID = 0x4; 2449 const AFSVOL_VOL_STAT_DOW3_VALID = 0x8; 2450 const AFSVOL_VOL_STAT_DOW4_VALID = 0x10; 2451 const AFSVOL_VOL_STAT_DOW5_VALID = 0x20; 2452 const AFSVOL_VOL_STAT_DOW6_VALID = 0x40; 2453 const AFSVOL_VOL_STAT_DOW_FUZZY = 0x80; 2455 struct AFSVol_stat_use_per_dow { 2456 afs_uint64 stat_dow[7]; 2457 afs_uint32 stat_flags; 2458 }; 2460 enum AFSVol_vol_state_expl { 2461 AFSVOL_VOL_STATE_EXPL_NONE = 0, 2462 AFSVOL_VOL_STATE_EXPL_UNKNOWN = 1, 2463 AFSVOL_VOL_STATE_EXPL_OUT_OF_SERVICE = 2, 2464 AFSVOL_VOL_STATE_EXPL_DELETED = 3, 2465 AFSVOL_VOL_STATE_EXPL_READY = 4, 2466 AFSVOL_VOL_STATE_EXPL_ATTACHING = 5, 2467 AFSVOL_VOL_STATE_EXPL_DETACHING = 6, 2468 AFSVOL_VOL_STATE_EXPL_BUSY = 7, 2469 AFSVOL_VOL_STATE_EXPL_IO_BUSY = 8, 2470 AFSVOL_VOL_STATE_EXPL_SALVAGING = 9, 2471 AFSVOL_VOL_STATE_EXPL_SALVAGE_NEEDED = 10, 2472 AFSVOL_VOL_STATE_EXPL_ERROR = 11, 2473 AFSVOL_VOL_STATE_EXPL_VOLUME_OPERATION = 12 2474 }; 2476 enum AFSVol_program_type { 2477 AFSVOL_PROGRAM_TYPE_NONE = 0, 2478 AFSVOL_PROGRAM_TYPE_FILE_SERVER = 1, 2479 AFSVOL_PROGRAM_TYPE_VOLUME_SERVER = 2, 2480 AFSVOL_PROGRAM_TYPE_SALVAGER = 3, 2481 AFSVOL_PROGRAM_TYPE_SALVAGE_SERVER = 4, 2482 AFSVOL_PROGRAM_TYPE_VOLUME_UTILITY = 5, 2483 AFSVOL_PROGRAM_TYPE_UNKNOWN = 6 2484 }; 2486 ext-union AFSVol_TLV_value switch(AFSVol_TLV_type type) { 2487 case AFSVOL_TLV_TYPE_NULL: 2488 void; 2490 case AFSVOL_TLV_TYPE_TRUE: 2491 void; 2493 case AFSVOL_TLV_TYPE_FALSE: 2494 void; 2496 case AFSVOL_TLV_TYPE_UINT64: 2497 afs_uint64 u_u64; 2499 case AFSVOL_TLV_TYPE_VOL_ID: 2500 afs_uint64 u_vol_id; 2502 case AFSVOL_TLV_TYPE_PART_ID: 2503 afs_uint64 u_part_id; 2505 case AFSVOL_TLV_TYPE_DISK_BLOCKS: 2506 afs_uint64 u_disk_blocks; 2508 case AFSVOL_TLV_TYPE_STAT_COUNTER: 2509 afs_uint64 u_stat_counter; 2511 case AFSVOL_TLV_TYPE_BIT64: 2512 afs_uint64 u_bit64; 2514 case AFSVOL_TLV_TYPE_INT64: 2515 afs_int64 u_s64; 2517 case AFSVOL_TLV_TYPE_STAT_GAUGE: 2518 afs_int64 u_stat_gauge; 2520 case AFSVOL_TLV_TYPE_UINT64_VEC: 2521 afs_uint64 u_u64_vec; 2523 case AFSVOL_TLV_TYPE_VOL_ID_VEC: 2524 afs_uint64 u_vol_id_vec; 2526 case AFSVOL_TLV_TYPE_PART_ID_VEC: 2527 afs_uint64 u_part_id_vec; 2529 case AFSVOL_TLV_TYPE_INT64_VEC: 2530 afs_int64 u_s64_vec; 2532 case AFSVOL_TLV_TYPE_TIME_ABS: 2533 AFSTime u_time_abs; 2535 case AFSVOL_TLV_TYPE_TIME_REL: 2536 AFSRelTimestamp u_time_rel; 2538 case AFSVOL_TLV_TYPE_TIME_ABS_VEC: 2539 AFSTime u_time_abs_vec; 2541 case AFSVOL_TLV_TYPE_TIME_REL_VEC: 2542 AFSRelTimestamp u_time_rel_vec; 2544 case AFSVOL_TLV_TYPE_UUID: 2545 afsUUID u_uuid; 2547 case AFSVOL_TLV_TYPE_STRING: 2548 string u_string; 2550 case AFSVOL_TLV_TYPE_VOL_DOW_USE: 2551 /* type defined later in this memo */ 2552 AFSVol_stat_use_per_dow u_vol_dow_use; 2554 case AFSVOL_TLV_TYPE_OPAQUE: 2555 opaque u_opaque; 2556 }; 2558 /* registrar-controlled tag namespace */ 2559 enum AFSVol_TLV_tag { 2560 AFSVOL_TLV_TAG_EOS = 0, 2561 AFSVOL_TLV_TAG_VOL_NAME = 1, 2562 AFSVOL_TLV_TAG_VOL_STATUS = 2, 2563 AFSVOL_TLV_TAG_VOL_IN_USE = 3, 2564 AFSVOL_TLV_TAG_VOL_ID = 4, 2565 AFSVOL_TLV_TAG_VOL_TYPE = 5, 2566 AFSVOL_TLV_TAG_VOL_CLONE_ID = 6, 2567 AFSVOL_TLV_TAG_VOL_BACKUP_ID = 7, 2568 AFSVOL_TLV_TAG_VOL_PARENT_ID = 8, 2569 AFSVOL_TLV_TAG_VOL_COPY_DATE = 9, 2570 AFSVOL_TLV_TAG_VOL_CREATE_DATE = 10, 2571 AFSVOL_TLV_TAG_VOL_ACCESS_DATE = 11, 2572 AFSVOL_TLV_TAG_VOL_UPDATE_DATE = 12, 2573 AFSVOL_TLV_TAG_VOL_BACKUP_DATE = 13, 2574 AFSVOL_TLV_TAG_VOL_SIZE = 14, 2575 AFSVOL_TLV_TAG_VOL_FILE_COUNT = 15, 2576 AFSVOL_TLV_TAG_VOL_QUOTA_BLOCKS = 16, 2577 AFSVOL_TLV_TAG_VOL_STAT_USE_TODAY = 17, 2578 AFSVOL_TLV_TAG_VOL_STAT_USE_PER_DOW = 18, 2579 AFSVOL_TLV_TAG_VOL_STAT_READS = 19, 2580 AFSVOL_TLV_TAG_VOL_STAT_WRITES = 20, 2581 AFSVOL_TLV_TAG_VOL_STAT_FILE_SAME_AUTHOR = 21, 2582 AFSVOL_TLV_TAG_VOL_STAT_FILE_DIFFERENT_AUTHOR = 22, 2583 AFSVOL_TLV_TAG_VOL_STAT_DIR_SAME_AUTHOR = 23, 2584 AFSVOL_TLV_TAG_VOL_STAT_DIR_DIFFERENT_AUTHOR = 24, 2585 AFSVOL_TLV_TAG_VOL_TRANS_ID = 25, 2586 AFSVOL_TLV_TAG_VOL_TRANS_TIME = 26, 2587 AFSVOL_TLV_TAG_VOL_TRANS_CREATE_TIME = 27, 2588 AFSVOL_TLV_TAG_VOL_TRANS_RETURN_CODE = 28, 2589 AFSVOL_TLV_TAG_VOL_TRANS_ATTACH_MODE = 29, 2590 AFSVOL_TLV_TAG_VOL_TRANS_STATUS = 30, 2591 AFSVOL_TLV_TAG_VOL_TRANS_FLAGS = 31, 2592 AFSVOL_TLV_TAG_VOL_TRANS_LAST_PROC_NAME = 32, 2593 AFSVOL_TLV_TAG_VOL_TRANS_CALL_VALID = 33, 2594 AFSVOL_TLV_TAG_VOL_TRANS_READ_NEXT = 34, 2595 AFSVOL_TLV_TAG_VOL_TRANS_XMIT_NEXT = 35, 2596 AFSVOL_TLV_TAG_VOL_TRANS_LAST_RECV_TIME = 36, 2597 AFSVOL_TLV_TAG_VOL_TRANS_LAST_SEND_TIME = 37, 2598 AFSVOL_TLV_TAG_VOL_IN_SERVICE = 38, 2599 AFSVOL_TLV_TAG_VOL_BLESSED = 39, 2600 AFSVOL_TLV_TAG_VOL_RESTORED_FROM_ID = 40, 2601 AFSVOL_TLV_TAG_VOL_DESTROYED = 41, 2602 AFSVOL_TLV_TAG_VOL_NEEDS_SALVAGE = 42, 2603 AFSVOL_TLV_TAG_VOL_OFFLINE_MESSAGE = 43, 2604 AFSVOL_TLV_TAG_VOL_EXPIRATION_DATE = 44, 2605 AFSVOL_TLV_TAG_VOL_QUOTA_RESERVATION = 45, 2606 AFSVOL_TLV_TAG_VOL_STAT_USE_TODAY_DATE = 46, 2607 AFSVOL_TLV_TAG_VOL_STATE_ONLINE = 47, 2608 AFSVOL_TLV_TAG_VOL_STATE_AVAILABLE = 48, 2609 AFSVOL_TLV_TAG_VOL_STATE_EXPL = 49, 2610 AFSVOL_TLV_TAG_VOL_STATE_DAFS_RAW = 50, 2611 AFSVOL_TLV_TAG_VOL_STATE_OWNING_PROCESS = 51, 2612 AFSVOL_TLV_TAG_VOL_QUOTA_BLOCKS_STORED_LOCALLY = 52, 2613 AFSVOL_TLV_TAG_VOL_QUOTA_FILES = 53 2614 }; 2616 struct AFSVol_TLV { 2617 afs_uint32 tlv_tag; 2618 afs_uint32 tlv_flags; 2619 AFSVol_TLV_value tlv_value; 2620 }; 2622 struct AFSVol_TLV_query { 2623 AFSVol_TLV_tag tq_tag; 2624 AFSVol_TLV_value tq_qualifier; 2625 }; 2627 struct AFSVol_TLV_store { 2628 AFSVol_TLV ts_tuple; 2629 AFSVol_TLV_value ts_qualifier; 2630 }; 2632 typedef afs_uint64 AFSVol_TLV_TSV; 2633 typedef AFSVol_TLV_tag AFSVol_TLV_tag_vec; 2634 typedef AFSVol_TLV_query AFSVol_TLV_query_vec; 2635 typedef AFSVol_TLV AFSVol_TLV_vec; 2636 typedef afs_uint64 AFSVol_TLV_part_id_vec; 2637 typedef afs_uint64 AFSVol_TLV_vol_id_vec; 2638 typedef AFSVol_TLV_store AFSVol_TLV_store_vec; 2639 typedef afs_int32 AFSVol_TLV_result_vec; 2641 struct AFSVol_TLV_vol_list { 2642 afs_uint64 partId; 2643 AFSVol_TLV_Vol_id_vec * volIds; 2644 }; 2646 typedef struct AFSVol_TLV_vol_list 2647 AFSVol_TLV_get_filter; 2649 proc GetVolumeTLVTags( 2650 IN AFSVol_TLV_tag offset, 2651 OUT AFSVol_TLV_tag_vec * tags, 2652 OUT AFSVol_TLV_TSV * tsv 2653 ) = XXX; 2655 proc GetOneVolumeTLV( 2656 IN afs_uint64 partId, 2657 IN afs_uint64 volId, 2658 IN AFSVol_TLV_query_vec * queries, 2659 OUT AFSVol_TLV_vec * tuples, 2660 OUT AFSVol_TLV_TSV * tsv 2661 ) = XXX; 2663 proc GetVolumesTLV( 2664 IN AFSVol_TLV_get_filter * filter, 2665 IN AFSVol_TLV_query_vec * queries, 2666 OUT AFSVol_TLV_TSV * tsv 2667 ) split = XXX; 2669 proc SetVolumeTLV( 2670 IN afs_int32 trans, 2671 IN AFSVol_TLV_TSV assert_tsv 2672 IN AFSVol_TLV_store_vec * tuples, 2673 OUT AFSVol_TLV_result_vec * results, 2674 OUT AFSVol_TLV_TSV * server_tsv 2675 ) = XXX; 2677 Figure 7 2679 Authors' Addresses 2681 Thomas Keiser 2682 Sine Nomine Associates 2683 43596 Blacksmith Square 2684 Ashburn, VA 20147 2685 USA 2687 Email: tkeiser@gmail.com 2689 Steven Jenkins 2691 Email: steven.jenkins@gmail.com 2693 Andrew Deason (editor) 2694 Sine Nomine Associates 2695 43596 Blacksmith Square 2696 Ashburn, Virginia 20147-4606 2697 USA 2699 Phone: +1 703 723 6673 2700 Email: adeason@sinenomine.net