idnits 2.17.1 draft-ietf-nfsv4-federated-fs-protocol-13.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 25, 2012) is 4230 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: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '0' on line 1528 -- Looks like a reference, but probably isn't: '255' on line 1528 ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Obsolete normative reference: RFC 5661 (Obsoleted by RFC 8881) Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NFSv4 Working Group J. Lentini 3 Internet-Draft NetApp 4 Intended status: Standards Track D. Ellard 5 Expires: March 29, 2013 Raytheon BBN Technologies 6 R. Tewari 7 IBM Almaden 8 C. Lever, Ed. 9 Oracle Corporation 10 September 25, 2012 12 NSDB Protocol for Federated Filesystems 13 draft-ietf-nfsv4-federated-fs-protocol-13 15 Abstract 17 This document describes a filesystem federation protocol that enables 18 file access and namespace traversal across collections of 19 independently administered fileservers. The protocol specifies a set 20 of interfaces by which fileservers with different administrators can 21 form a fileserver federation that provides a namespace composed of 22 the filesystems physically hosted on and exported by the constituent 23 fileservers. 25 Requirements Language 27 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 28 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 29 document are to be interpreted as described in [RFC2119]. 31 Status of this Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at http://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on March 29, 2013. 48 Copyright Notice 49 Copyright (c) 2012 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the Simplified BSD License. 62 This document may contain material from IETF Documents or IETF 63 Contributions published or made publicly available before November 64 10, 2008. The person(s) controlling the copyright in some of this 65 material may not have granted the IETF Trust the right to allow 66 modifications of such material outside the IETF Standards Process. 67 Without obtaining an adequate license from the person(s) controlling 68 the copyright in such materials, this document may not be modified 69 outside the IETF Standards Process, and derivative works of it may 70 not be created outside the IETF Standards Process, except to format 71 it for publication as an RFC or to translate it into languages other 72 than English. 74 Table of Contents 76 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 77 2. Overview of Features and Concepts . . . . . . . . . . . . . . 6 78 2.1. File-access Protocol . . . . . . . . . . . . . . . . . . . 6 79 2.2. File-access Client . . . . . . . . . . . . . . . . . . . . 6 80 2.3. Fileserver . . . . . . . . . . . . . . . . . . . . . . . . 6 81 2.4. Referral . . . . . . . . . . . . . . . . . . . . . . . . . 6 82 2.5. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 6 83 2.6. Fileset . . . . . . . . . . . . . . . . . . . . . . . . . 7 84 2.7. Fileset Name (FSN) . . . . . . . . . . . . . . . . . . . . 7 85 2.8. Fileset Location (FSL) . . . . . . . . . . . . . . . . . . 8 86 2.8.1. The NFS URI scheme . . . . . . . . . . . . . . . . . . 9 87 2.8.2. Mutual Consistency across Fileset Locations . . . . . 10 88 2.8.3. Caching of Fileset Locations . . . . . . . . . . . . . 11 89 2.8.4. Generating A Referral from Fileset Locations . . . . . 12 90 2.9. Namespace Database (NSDB) . . . . . . . . . . . . . . . . 13 91 2.10. Junctions and Referrals . . . . . . . . . . . . . . . . . 14 92 2.11. Unified Namespace and the Root Fileset . . . . . . . . . . 14 93 2.12. UUID Considerations . . . . . . . . . . . . . . . . . . . 15 94 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 95 3.1. Creating a Fileset and its FSL(s) . . . . . . . . . . . . 16 96 3.1.1. Creating a Fileset and an FSN . . . . . . . . . . . . 17 97 3.1.2. Adding a Replica of a Fileset . . . . . . . . . . . . 17 98 3.2. Junction Resolution . . . . . . . . . . . . . . . . . . . 17 99 3.3. Example Use Cases for Fileset Annotations . . . . . . . . 18 100 4. NSDB Configuration and Schema . . . . . . . . . . . . . . . . 19 101 4.1. LDAP Configuration . . . . . . . . . . . . . . . . . . . . 19 102 4.2. LDAP Schema . . . . . . . . . . . . . . . . . . . . . . . 20 103 4.2.1. LDAP Attributes . . . . . . . . . . . . . . . . . . . 23 104 4.2.2. LDAP Objects . . . . . . . . . . . . . . . . . . . . . 37 105 5. NSDB Operations . . . . . . . . . . . . . . . . . . . . . . . 40 106 5.1. NSDB Operations for Administrators . . . . . . . . . . . . 41 107 5.1.1. Create an FSN . . . . . . . . . . . . . . . . . . . . 41 108 5.1.2. Delete an FSN . . . . . . . . . . . . . . . . . . . . 42 109 5.1.3. Create an FSL . . . . . . . . . . . . . . . . . . . . 43 110 5.1.4. Delete an FSL . . . . . . . . . . . . . . . . . . . . 46 111 5.1.5. Update an FSL . . . . . . . . . . . . . . . . . . . . 47 112 5.2. NSDB Operations for Fileservers . . . . . . . . . . . . . 48 113 5.2.1. NSDB Container Entry (NCE) Enumeration . . . . . . . . 48 114 5.2.2. Lookup FSLs for an FSN . . . . . . . . . . . . . . . . 48 115 5.3. NSDB Operations and LDAP Referrals . . . . . . . . . . . . 49 116 6. Security Considerations . . . . . . . . . . . . . . . . . . . 50 117 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51 118 7.1. Registry for the fedfsAnnotation Key Namespace . . . . . . 51 119 7.2. Registry for FedFS Object Identifiers . . . . . . . . . . 51 120 7.3. LDAP Descriptor Registration . . . . . . . . . . . . . . . 53 121 8. Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 122 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 59 123 9.1. Normative References . . . . . . . . . . . . . . . . . . . 59 124 9.2. Informative References . . . . . . . . . . . . . . . . . . 60 125 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 61 126 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 62 128 1. Introduction 130 A federated filesystem enables file access and namespace traversal in 131 a uniform, secure and consistent manner across multiple independent 132 fileservers within an enterprise or across multiple enterprises. 134 This document specifies a set of protocols that allow fileservers, 135 possibly from different vendors and with different administrators, to 136 cooperatively form a federation containing one or more federated 137 filesystems. Each federated filesystem's namespace is composed of 138 the filesystems physically hosted on and exported by the federation's 139 fileservers. A federation MAY contain a common namespace across all 140 its fileservers. A federation MAY project multiple namespaces and 141 enable clients to traverse each one. A federation MAY contain an 142 arbitrary number of namespace repositories, each belonging to a 143 different administrative entity, and each rendering a part of the 144 namespace. A federation MAY also have an arbitrary number of 145 administrative entities responsible for administering disjoint 146 subsets of the fileservers. 148 Traditionally, building a namespace that spans multiple fileservers 149 has been difficult for two reasons. First, the fileservers that 150 export pieces of the namespace are often not in the same 151 administrative domain. Second, there is no standard mechanism for 152 the fileservers to cooperatively present the namespace. Fileservers 153 may provide proprietary management tools and in some cases an 154 administrator may be able to use the proprietary tools to build a 155 shared namespace out of the exported filesystems. However, relying 156 on vendor-specific proprietary tools does not work in larger 157 enterprises or when collaborating across enterprises because the 158 fileservers are likely to be from multiple vendors or use different 159 software versions, each with their own namespace protocols, with no 160 common mechanism to manage the namespace or exchange namespace 161 information. 163 The federated filesystem protocols in this document define how to 164 construct a namespace accessible by an NFSv4.0 [3530bis], NFSv4.1 165 [RFC5661] or newer client and have been designed to accommodate other 166 file access protocols in the future. 168 The requirements for federated filesystems are described in 169 [RFC5716]. A protocol for administering a fileserver's namespace is 170 described in [FEDFS-ADMIN]. The mechanism for discovering the root 171 of a federated namespace is described in [RFC6641]. 173 In the rest of the document, the term fileserver denotes a fileserver 174 that is part of a federation. 176 2. Overview of Features and Concepts 178 2.1. File-access Protocol 180 A file-access protocol is a network protocol for accessing data. The 181 NFSv4.0 protocol [3530bis] is an example of a file-access protocol. 183 2.2. File-access Client 185 File-access clients are standard off-the-shelf network attached 186 storage (NAS) clients that communicate with fileservers using a 187 standard file-access protocol. 189 2.3. Fileserver 191 Fileservers are servers that store physical fileset data, or refer 192 file-access clients to other fileservers. A fileserver provides 193 access to its shared filesystem data via a file-access protocol. A 194 fileserver may be implemented in a number of different ways, 195 including a single system, a cluster of systems, or some other 196 configuration. 198 2.4. Referral 200 A referral is a mechanism by which a fileserver redirects a file- 201 access client to a different fileserver or export. The exact 202 information contained in a referral varies from one file-access 203 protocol to another. The NFSv4.0 protocol, for example, defines the 204 fs_locations attribute for returning referral information to NFSv4.0 205 clients. The NFSv4.1 protocol introduces the fs_locations_info 206 attribute that can return richer referral information to its clients. 207 NFSv4.1 fileservers may use either attribute during a referral. Both 208 attributes are defined in [RFC5661]. 210 2.5. Namespace 212 The goal of a unified namespace is to make all managed data available 213 to any file-access client via the same path in a common filesystem 214 namespace. This should be achieved with minimal or zero 215 configuration on file-access clients. In particular, updates to the 216 common namespace should not require configuration changes to any 217 file-access client. 219 Filesets, which are the unit of data management, are a set of files 220 and directories. From the perspective of file-access clients, the 221 common namespace is constructed by mounting filesets that are 222 physically located on different fileservers. The namespace, which is 223 defined in terms of fileset names and locations, is stored in a set 224 of namespace repositories, each managed by an administrative entity. 226 The namespace schema defines the model used for populating, 227 modifying, and querying the namespace repositories. It is not 228 required by the federation that the namespace be common across all 229 fileservers. It should be possible to have several independently 230 rooted namespaces. 232 2.6. Fileset 234 A fileset is loosely defined as a set of files and the directory tree 235 that contains them. The fileset abstraction is the basic unit of 236 data management. Depending on the configuration, a fileset may be 237 anything from an individual directory of an exported filesystem to an 238 entire exported filesystem on a fileserver. 240 2.7. Fileset Name (FSN) 242 A fileset is uniquely represented by its fileset name (FSN). An FSN 243 is considered unique across a federation. After an FSN is created, 244 it is associated with one or more fileset locations (FSLs) on one or 245 more fileservers. 247 An FSN consists of: 249 NsdbName: the network location of the NSDB node that contains 250 authoritative information for this FSN. 252 FsnUuid: a UUID (universally unique identifier), conforming to 253 [RFC4122], that is used to uniquely identify an FSN. 255 FsnTTL: the time in seconds during which the FSN's FSL 256 information may be cached. 258 The FsnUuid is a required attribute of an FSN record, but the 259 NsdbName is not stored as an attribute of the record. The NsdbName 260 is obvious to NSDB clients, and is indeed authenticated in cases 261 where TLS security is in effect. 263 An FSN record also contains a cache time-to-live attribute. The 264 FsnUuid and NsdbName values never change during an FSN's lifetime. 265 However, an FSN's FSL information can change over time, and is 266 typically cached on fileservers for performance. More detail is 267 provided in Section 2.8.3. 269 An FSN record may also contain: 271 Annotations: optional name/value pairs that can be interpreted by 272 a fileserver. The semantics of this field are not defined by 273 this document. These tuples are intended to be used by higher- 274 level protocols. 276 Descriptions: optional text descriptions. The semantics of this 277 field are not defined by this document. 279 2.8. Fileset Location (FSL) 281 An FSL describes one physical location where a complete copy of the 282 fileset's data resides. An FSL contains generic and type specific 283 information which together describe how to access the fileset data at 284 this location. An FSL's attributes can be used by a fileserver to 285 decide which locations it will return to a file-access client. 287 An FSL consists of: 289 FslUuid: a UUID, conforming to [RFC4122], that is used to 290 uniquely identify an FSL. 292 FsnUuid: the UUID of the FSL's FSN. 294 NsdbName: the network location of the NSDB node that contains 295 authoritative information for this FSL. 297 The NsdbName is not stored as an attribute of an FSL record for the 298 same reason it is not stored in FSN records. 300 An FSL record may also contain: 302 Annotations: optional name/value pairs that can be interpreted by 303 a fileserver. The semantics of this field are not defined by 304 this document. These tuples are intended to be used by higher- 305 level protocols. 307 Descriptions: optional text descriptions. The semantics of this 308 field are not defined by this document. 310 This document defines an FSL subtype for NFS. An NFS FSL contains 311 information suitable for use in one of the NFSv4 referral attributes 312 (e.g., fs_locations or fs_locations_info). 314 A fileset MAY be accessible by protocols other than NFS. For each 315 such protocol, a corresponding FSL subtype SHOULD be defined. The 316 contents and format of such FSL subtypes are not defined in this 317 document. 319 2.8.1. The NFS URI scheme 321 To capture the location of an NFSv4 fileset, we extend the NFS URL 322 scheme specified in [RFC2224]. This extention follows rules for 323 defining Uniform Resource Identifier schemes in [RFC3986]. In the 324 following text, we refer to this extended NFS URL scheme as an NFS 325 URI. 327 An NFS URI MUST contain both an authority and a path component. It 328 MUST NOT contain a query component or a fragment component. Use of 329 the familiar "nfs" scheme name is retained. 331 2.8.1.1. The NFS URI authority component 333 The rules for encoding the authority component of a generic URI are 334 specified in section 3.2 of [RFC3986]. The authority component of an 335 NFS URI MUST contain the host subcomponent. For globally-scoped NFS 336 URIs, a hostname used in such URIs SHOULD be a fully qualified domain 337 name. See section 3.2.2 of [RFC3986] for rules on encoding non-ASCII 338 characters in hostnames. 340 An NFS URI MAY contain a port subcomponent as described in section 341 3.2.3 of [RFC3986]. If this subcomponent is missing, a port value of 342 2049 is assumed. 344 2.8.1.2. The NFS URI path component 346 The rules for encoding the path component of a generic URI are 347 specified in section 3.3 of [RFC3986]. 349 According to sections 5 and 6 of [RFC2224], NFS URLs specify a 350 pathname relative to an NFS fileserver's "public filehandle." 351 However, NFSv4 fileservers do not expose a "public filehandle." 352 Instead, NFSv4 pathnames contained in an NFS URI are evaluated 353 relative to the pseudoroot of the fileserver identified in the URI's 354 authority component. 356 The component4 elements of an NFSv4 pathname are encoded as path 357 segments in an NFS URI. NFSv4 pathnames MUST be expressed in an NFS 358 URI as an absolute path. An NFS URI path component MUST NOT be 359 empty. The NFS URI path component starts with a slash ("/") 360 character, followed by one or more path segments which each start 361 with a slash ("/") character [RFC3986]. 363 Therefore, a double slash always follows the authority component of 364 an NFS URI. For example, the NFSv4 pathname "/" is represented by 365 two slash ("/") characters following an NFS URI's authority 366 component. 368 The component4 elements of an NFS pathname SHOULD be prepared using 369 the component4 rules defined in Chapter 12 "Internationalization" of 370 [3530bis] prior to encoding the path component of an NFS URI. 371 Because a URI is a US-ASCII string, any non-ASCII UTF-8 code point in 372 a component4 element MUST be represented by URI percent encoding. 373 URI-reserved characters such as the slash ("/") character contained 374 in a component4 element MUST be represented by URI percent encoding. 376 2.8.1.3. Encoding an NFS location in an FSL 378 The path component of an NFS URI encodes the "rootpath" field of the 379 NFSv4 fs_location4 data type or the "fli_rootpath" of the NFSv4 380 fs_locations_item4 data type (see [RFC5661]). 382 In its "server" field, the NFSv4 fs_location4 data type contains a 383 list of universal addresses or UTF-8 hostnames. Each may optionally 384 include a port number. The NFSv4 fs_locations_item4 data type 385 contains this data in its "fli_entries" field (see [RFC5661]). This 386 information is encoded in the authority component of an NFS URI. 388 The "server" and "fli_entries" fields can encode multiple server 389 hostnames that share the same pathname. An NFS URI, and hence an FSL 390 record, represents only a single hostname and pathname pair. An NFS 391 fileserver MUST NOT combine a set of FSL records into a single 392 fs_location4 or fs_locations_item4 unless each FSL record in the set 393 contains the same rootpath value and extended filesystem information. 395 2.8.2. Mutual Consistency across Fileset Locations 397 All of the FSLs that have the same FSN (and thereby reference the 398 same fileset) are equivalent from the point of view of access by a 399 file-access client. Different fileset locations for an FSN represent 400 the same data, though potentially at different points in time. 401 Fileset locations are equivalent but not identical. Locations may 402 either be read-only or read-write. Typically, multiple read-write 403 locations are backed by a clustered filesystem while read-only 404 locations are replicas created by a federation-initiated or external 405 replication operation. Read-only locations may represent consistent 406 point-in-time copies of a read-write location. The federation 407 protocols, however, cannot prevent subsequent changes to a read-only 408 location nor guarantee point-in-time consistency of a read-only 409 location if the read-write location is changing. 411 Regardless of the type, one file-access client may be referred to a 412 location described by one FSL while another client chooses to use a 413 location described by another FSL. Since updates to each fileset 414 location are not controlled by the federation protocol, it is the 415 responsibility of administrators to guarantee the functional 416 equivalence of the data. 418 The federation protocols do not guarantee that different fileset 419 locations are mutually consistent in terms of the currency of their 420 data. However, they provide a means to publish currency information 421 so that all fileservers in a federation can convey the same 422 information to file-access clients during referrals. Clients use 423 this information to ensure they do not revert to an out-of-date 424 version of a fileset's data when switching between fileset locations. 425 NFSv4.1 provides guidance on how replication can be handled in such a 426 manner. In particular see Section 11.7 of [RFC5661]. 428 2.8.3. Caching of Fileset Locations 430 To resolve an FSN to a set of FSL records, a fileserver queries the 431 NSDB node named in the FSN for FSL records associated with this FSN. 433 The period of time during which these FSL records MAY be cached is 434 indicated by the parent FSN's TTL attribute. A value of zero 435 indicates that the results of resolving this FSN SHOULD NOT be 436 cached. In addition, a fileserver SHOULD check back with the NSDB 437 node after the FSN TTL has expired to discover if any new FSL records 438 have been added for this FSN. 440 The combination of FSL caching and FSL migration presents a 441 challenge. For example, suppose there are three fileservers named A, 442 B, and C. Suppose further that fileserver A contains a junction J to 443 fileset X stored on fileserver B. 445 Now suppose that fileset X is migrated from fileserver B to 446 fileserver C, and the corresponding FSL information for fileset X in 447 the authoritative NSDB is updated. 449 If fileserver A has cached FSLs for fileset X, a file-access client 450 traversing junction J on fileserver A will be referred to fileserver 451 B, even though fileset X has migrated to fileserver C. If fileserver 452 A had not cached the FSL records, it would have queried the NSDB and 453 obtained the correct location of fileset X. 455 Typically, the process of fileset migration leaves a redirection on 456 the source fileserver in place of a migrated fileset (without such a 457 redirection, file-access clients would find an empty space where the 458 migrated fileset was, which defeats the purpose of a managed 459 migration). 461 This redirection might be a new junction that targets the same FSN as 462 other junctions referring to the migrated fileset, or it might be 463 some other kind of directive, depending on the fileserver 464 implementation, that simply refers file-access clients to the new 465 location of the migrated fileset. 467 Back to our example. Suppose, as part of the migration process, a 468 junction replaces fileset X on fileserver B. Later, either: 470 o New file-access clients are referred to fileserver B by stale FSL 471 information cached on fileserver A, or 473 o File-access clients continue to access fileserver B because they 474 cache stale location data for fileset X. 476 In either case, thanks to the redirection, file-access clients are 477 informed by fileserver B that fileset X has moved to fileserver C. 479 Such redirecting junctions (here, on fileserver B) would not be 480 required to be in place forever. They need to stay in place at least 481 until FSL entries cached on fileservers and locations cached on file- 482 access clients for the target fileset are invalidated. 484 An FSL's parent FSN contains a TTL field which contains a count in 485 seconds of the time interval the FSL MAY be cached. This is an upper 486 bound for the lifetime of the cached information, and thus can act as 487 a lower bound for the lifetime of redirecting junctions. 489 For example, suppose this field contains the value 3600 seconds (one 490 hour). In such a case, administrators SHOULD keep the redirection in 491 place for at least one hour after a fileset migration has taken 492 place, and FSL data MUST NOT be cached by a referring fileserver for 493 more than one hour without a refresh. 495 To get file-access clients to access the destination fileserver more 496 quickly, administrators SHOULD set the FSN TTL field of the migrated 497 fileset to a low number or zero before migration begins. It can be 498 reset to a more reasonable number at a later point. 500 Note that some file-access protocols do not communicate location 501 cache expiry information to file-access clients. In some cases it 502 may be difficult to determine an appropriate lifetime for redirecting 503 junctions because file-access clients may cache location information 504 indefinitely. 506 2.8.4. Generating A Referral from Fileset Locations 508 After resolving an FSN to a set of FSL records, the fileserver 509 generates a referral to redirect a file-access client to one or more 510 of the FSN's FSLs. The fileserver converts the FSL records to a 511 referral format understood by a particular file-access client, such 512 as an NFSv4 fs_locations or fs_locations_info attribute. 514 To give file-access clients as many options as possible, the 515 fileserver SHOULD include the maximum possible number of FSL records 516 in a referral. However, the fileserver MAY omit some of the FSL 517 records from the referral. For example, the fileserver might omit an 518 FSL record because of limitations in the file access protocol's 519 referral format. 521 For a given FSL record, the fileserver MAY convert or reduce the FSL 522 record's contents in a manner appropriate to the referral format. 523 For example, an NFS FSL record contains all the data necessary to 524 construct an fs_locations_info attribute, but an fs_locations_info 525 attribute contains several pieces of information that are not found 526 in the simpler fs_locations attribute. A fileserver constructs 527 entries in an fs_locations attribute using the relevant contents of 528 an NFS FSL record. 530 Whenever the fileserver converts or reduces FSL data, the fileserver 531 SHOULD attempt to maintain the original meaning where possible. For 532 example, an NFS FSL record contains the rank and order information 533 that is included in an fs_locations_info attribute (see NFSv4.1's 534 FSLI4BX_READRANK, FSLI4BX_READORDER, FSLI4BX_WRITERANK, and 535 FSLI4BX_WRITEORDER). While this rank and order information is not 536 explicitly expressible in an fs_locations attribute, the fileserver 537 can arrange the fs_locations attribute's locations list based on the 538 rank and order values. 540 Another example: A single NFS FSL record contains the hostname of one 541 fileserver. A single fs_locations attribute can contain a list of 542 fileserver names. An NFS fileserver MAY combine two or more FSL 543 records into a single entry in an fs_locations or fs_locations_info 544 array only if each FSL record contains the same pathname and extended 545 filesystem information. 547 Refer to the NFSv4.1 protocol specification [RFC5661], sections 11.9 548 and 11.10, for further details. 550 2.9. Namespace Database (NSDB) 552 The NSDB service is a federation-wide service that provides 553 interfaces to define, update, and query FSN information, FSL 554 information, and FSN to FSL mapping information. 556 An individual repository of namespace information is called an NSDB 557 node. The difference between the NSDB service and an NSDB node is 558 analogous to that between the DNS service and a particular DNS 559 server. 561 Each NSDB node is managed by a single administrative entity. A 562 single admininistrative entity can manage multiple NSDB nodes. 564 Each NSDB node stores the definition of the FSNs for which it is 565 authoritative. It also stores the definitions of the FSLs associated 566 with those FSNs. An NSDB node is authoritative for the filesets that 567 it defines. 569 Each NSDB node supports an LDAP [RFC4510] interface. The information 570 stored on an NSDB node is accessed and updated by LDAP clients. 572 An NSDB MAY be replicated throughout the federation. If an NSDB is 573 replicated, the NSDB MUST exhibit loose, converging consistency as 574 defined in [RFC3254]. The mechanism by which this is achieved is 575 outside the scope of this document. Many LDAP implementations 576 support replication. These features MAY be used to replicate the 577 NSDB. 579 2.10. Junctions and Referrals 581 A junction is a point in a particular fileset namespace where a 582 specific target fileset may be attached. If a file-access client 583 traverses the path leading from the root of a federated namespace to 584 the junction referring to a target fileset, it should be able to 585 mount and access the data in that target fileset (assuming 586 appropriate permissions). In other words, a junction can be viewed 587 as a reference from a directory in one fileset to the root of the 588 target fileset. 590 A junction can be implemented as a special marker on a directory, or 591 by some other mechanism in the fileserver's underlying filesystem. 592 What data is used by the fileserver to represent junctions is not 593 defined by this document. The essential property is that given a 594 junction, a fileserver must be able to find the FSN for the target 595 fileset. 597 When a file-access client reaches a junction, the fileserver refers 598 the client to a list of FSLs associated with the FSN targeted by the 599 junction. The client can then mount one of the associated FSLs. 601 The federation protocols do not limit where and how many times a 602 fileset is mounted in the namespace. Filesets can be nested; a 603 fileset can be mounted under another fileset. 605 2.11. Unified Namespace and the Root Fileset 607 The root fileset, when defined, is the top-level fileset of the 608 federation-wide namespace. The root of the unified namespace is the 609 top level directory of this fileset. A set of designated fileservers 610 in the federation can export the root fileset to render the 611 federation-wide unified namespace. When a file-access client mounts 612 the root fileset from any of these designated fileservers it can view 613 a common federation-wide namespace. 615 The root fileset could be implemented either as an exported NFS file 616 system or as data in the NSDB itself. The properties and schema 617 definition of an NSDB-based root fileset and the protocol details 618 that describe how to configure and replicate the root fileset are not 619 defined in this document. 621 2.12. UUID Considerations 623 To ensure FSN and FSL records are unique across a domain, FedFS 624 employs UUIDs conforming to [RFC4122] to form the distinguished names 625 of LDAP records containing FedFS data (see Section 4.2.2.2). 627 Because junctions store a tuple containing an FSN UUID and the name 628 and port of an NSDB node, an FSN UUID must be unique only on a single 629 NSDB node. An FSN UUID collision can be detected immediately when an 630 administrator attempts to publish an FSN or FSL by storing it under a 631 specific NCE on an authoritative NSDB host. 633 Note that one NSDB node may store multiple NCEs, each under a 634 different namingContext. If an NSDB node must contain more than one 635 NCE, the federation's admin entity SHOULD provide a robust method for 636 preventing FSN UUID collisions between FSNs that reside on the same 637 NSDB node but under different NCEs. 639 Because FSLs are children of FSNs, FSL UUIDs must be unique for just 640 a single FSN. As with FSNs, as soon as an FSL is published, its 641 uniqueness is guaranteed. 643 Of course, there is no way to guard against UUID re-use, but that is 644 highly unlikely provided that UUIDs are constructed carefully. 646 A fileserver performs the operations described in Section 5.2 as an 647 unauthenticated user. Thus distinguished names of FSN and FSL 648 records, as well as the FSN and FSL records themselves, are required 649 to be readable by anyone who can bind anonymously to an NSDB node. 650 Therefore FSN and FSL UUIDs should be considered public information. 652 Version 1 UUIDs contain a host's MAC address and a time stamp in the 653 clear. This gives provenance to each UUID, but attackers can use 654 such details to guess information about the host where the UUID was 655 generated. Security-sensitive installations should be aware that on 656 externally-facing NSDBs, UUIDs can reveal information about the hosts 657 where they are generated. 659 In addition, version 1 UUIDs depend on the notion that a hardware MAC 660 address is unique across machines. As virtual machines do not depend 661 on unique physical MAC addresses and in any event an administrator 662 can modify the physical MAC address, version 1 UUIDs are no longer 663 considered sufficient. 665 To minimize the probability of UUIDs colliding, a consistent 666 procedure for generating UUIDs should be used throughout a 667 federation. Within a federation, UUIDs SHOULD be generated using the 668 procedure described for version 4 of the UUID variant specified in 669 [RFC4122]. 671 3. Examples 673 In this section we provide examples and discussion of the basic 674 operations facilitated by the federated filesystem protocol: creating 675 a fileset, adding a replica of a fileset, resolving a junction, and 676 creating a junction. 678 3.1. Creating a Fileset and its FSL(s) 680 A fileset is the abstraction of a set of files and the directory tree 681 that contains them. The fileset abstraction is the fundamental unit 682 of data management in the federation. This abstraction is 683 implemented by an actual directory tree whose root location is 684 specified by a fileset location (FSL). 686 In this section, we describe the basic requirements for starting with 687 a directory tree and creating a fileset that can be used in the 688 federation protocols. Note that we do not assume that the process of 689 creating a fileset requires any transformation of the files or the 690 directory hierarchy. The only thing that is required by this process 691 is assigning the fileset a fileset name (FSN) and expressing the 692 location of the implementation of the fileset as an FSL. 694 There are many possible variations to this procedure, depending on 695 how the FSN that binds the FSL is created, and whether other replicas 696 of the fileset exist, are known to the federation, and need to be 697 bound to the same FSN. 699 It is easiest to describe this in terms of how to create the initial 700 implementation of the fileset, and then describe how to add replicas. 702 3.1.1. Creating a Fileset and an FSN 704 1. Choose the NSDB node that will keep track of the FSL(s) and 705 related information for the fileset. 707 2. Create an FSN in the NSDB node. 709 The FSN UUID is chosen by the administrator or generated 710 automatically by administration software. The former case is 711 used if the fileset is being restored, perhaps as part of 712 disaster recovery, and the administrator wishes to specify the 713 FSN UUID in order to permit existing junctions that reference 714 that FSN to work again. 716 At this point, the FSN exists, but its fileset locations are 717 unspecified. 719 3. For the FSN created above, create an FSL in the NSDB node that 720 describes the physical location of the fileset data. 722 3.1.2. Adding a Replica of a Fileset 724 Adding a replica is straightforward: the NSDB node and the FSN are 725 already known. The only remaining step is to add another FSL. 727 Note that the federation protocols provide only the mechanisms to 728 register and unregister replicas of a fileset. Fileserver-to- 729 fileserver replication protocols are not defined. 731 3.2. Junction Resolution 733 A fileset may contain references to other filesets. These references 734 are represented by junctions. If a file-access client requests 735 access to a fileset object that is a junction, the fileserver 736 resolves the junction to discover one or more FSLs that implement the 737 referenced fileset. 739 There are many possible variations to this procedure, depending on 740 how the junctions are represented by the fileserver and how the 741 fileserver performs junction resolution. 743 Step 4 is the only step that interacts directly with the federation 744 protocols. The rest of the steps may use platform-specific 745 interfaces. 747 1. The fileserver determines that the object being accessed is a 748 junction. 750 2. The fileserver does a local lookup to find the FSN of the target 751 fileset. 753 3. Using the FSN, the fileserver finds the NSDB node responsible for 754 the target FSN. 756 4. The fileserver contacts that NSDB node and asks for the set of 757 FSLs that implement the target FSN. The NSDB node responds with 758 a (possibly empty) set of FSLs. 760 5. The fileserver converts one or more of the FSLs to the location 761 type used by the file-access client (e.g., an NFSv4 fs_location 762 attribute as described in [RFC5661]). 764 6. The fileserver redirects (in whatever manner is appropriate for 765 the client) the client to the location(s). 767 3.3. Example Use Cases for Fileset Annotations 769 Fileset annotations MAY be used to convey additional attributes of a 770 fileset 772 For example, fileset annotations can be used to define relationships 773 between filesets that can be used by an auxiliary replication 774 protocol. Consider the scenario where a fileset is created and 775 mounted at some point in the namespace. A snapshot of the read-write 776 FSL of that fileset is taken periodically at different frequencies 777 (say, a daily or weekly snapshot). The different snapshots are 778 mounted at different locations in the namespace. 780 The daily snapshots are considered as different filesets from the 781 weekly ones, but both are related to the source fileset. We can 782 define an annotation labeling the filesets as source and replica. 783 The replication protocol can use this information to copy data from 784 one or more FSLs of the source fileset to all the FSLs of the replica 785 fileset. The replica filesets are read-only while the source fileset 786 is read-write. 788 This follows the traditional Andrew File System (AFS) model of 789 mounting the read-only volume at a path in the namespace different 790 from that of the read-write volume [AFS]. 792 The federation protocol does not control or manage the relationship 793 among filesets. It merely enables annotating the filesets with user- 794 defined relationships. 796 Another potential use for annotations is recording references to an 797 FSN. A single annotation containing the number of references could 798 be defined; or multiple annotations, one per reference, could be used 799 to store detailed information on the location of each reference. 801 As with the replication annotation described above, the maintenance 802 of reference information would not be controlled by the federation 803 protocol. The information would most likely be non-authoritative 804 because the ability to create a junction does not require the 805 authority to update the FSN record. In any event, such annotations 806 could be useful to administrators for determining if an FSN is 807 referenced by a junction. 809 4. NSDB Configuration and Schema 811 This section describes how an NSDB is constructed using an LDAP 812 Version 3 [RFC4510] Directory. Section 4.1 describes the basic 813 properties of the LDAP configuration that MUST be used in order to 814 ensure compatibility between different implementations. Section 4.2 815 defines the new LDAP attribute types, the new object types, and 816 specifies how the distinguished name (DN) of each object instance 817 MUST be constructed. 819 4.1. LDAP Configuration 821 An NSDB is constructed using an LDAP Directory. This LDAP Directory 822 MAY have multiple naming contexts. For each naming context, the LDAP 823 Directory's root DSE will have a namingContext attribute. Each 824 namingContext attribute contains the DN of the naming context's root 825 entry. For each naming context that contains federation entries 826 (e.g., FSNs and FSLs): 828 1. There MUST be an LDAP entry that is superior to all of the naming 829 context's federation entries in the Directory Information Tree 830 (DIT). This entry is termed the NSDB Container Entry (NCE). The 831 NCE's children are FSNs. An FSN's children are FSLs. 833 2. The naming context's root entry MUST include the 834 fedfsNsdbContainerInfo (defined below) as one of its object 835 classes. The fedfsNsdbContainerInfo's fedfsNceDN attribute is 836 used to locate the naming context's NCE. 838 If a naming context does not contain federation entries, it will not 839 contain an NCE and its root entry will not include a 840 fedfsNsdbContainerInfo as one of its object classes. 842 A fedfsNsdbContainerInfo's fedfsNceDN attribute contains the 843 Distinguished Name (DN) of the NSDB Container Entry residing under 844 this naming context. The fedfsNceDN attribute MUST NOT be empty. 846 For example, an LDAP directory might have the following entries: 848 -+ [root DSE] 849 | namingContext: o=fedfs 850 | namingContext: dc=example,dc=com 851 | namingContext: ou=system 852 | 853 | 854 +---- [o=fedfs] 855 | fedfsNceDN: o=fedfs 856 | 857 | 858 +---- [dc=example,dc=com] 859 | fedfsNceDN: ou=fedfs,ou=corp-it,dc=example,dc=com 860 | 861 | 862 +---- [ou=system] 864 In this case, the o=fedfs namingContext has an NSBD Container Entry 865 at o=fedfs, the dc=example,dc=com namingContext has an NSDB Container 866 Entry at ou=fedfs,ou=corp-it,dc=example,dc=com, and the ou=system 867 namingContext has no NSDB Container Entry. 869 The NSDB SHOULD be configured with one or more privileged LDAP users. 870 These users are able to modify the contents of the LDAP database. An 871 administrator that performs the operations described in Section 5.1 872 SHOULD authenticate using the DN of a privileged LDAP user. 874 It MUST be possible for an unprivileged (unauthenticated) user to 875 perform LDAP queries that access the NSDB data. A fileserver 876 performs the operations described in Section 5.2 as an unprivileged 877 user. 879 All implementations SHOULD use the same schema, or, at minimum, a 880 schema that includes all of the objects, with each of the attributes, 881 named in the following sections. 883 Given the above configuration guidelines, an NSDB SHOULD be 884 constructed using a dedicated LDAP directory. Separate LDAP 885 directories are RECOMMENDED for other purposes, such as storing user 886 account information. By using an LDAP directory dedicated to storing 887 NSDB records, there is no need to disturb the configuration of any 888 other LDAP directories that store information unrelated to an NSDB. 890 4.2. LDAP Schema 892 The schema definitions provided in this document use the LDAP schema 893 syntax defined in [RFC4512]. The definitions are formatted to allow 894 the reader to easily extract them from the document. The reader can 895 use the following shell script to extract the definitions: 897 899 #!/bin/sh 900 grep '^ *///' | sed 's?^ */// ??' | sed 's?^ *///$??' 902 904 If the above script is stored in a file called "extract.sh", and this 905 document is in a file called "spec.txt", then the reader can do: 907 909 sh extract.sh < spec.txt > fedfs.schema 911 913 The effect of the script is to remove leading white space from each 914 line, plus a sentinel sequence of "///". 916 As stated above, code components extracted from this document must 917 include the following license: 919 920 /// # 921 /// # Copyright (c) 2010-2012 IETF Trust and the persons identified 922 /// # as authors of the code. All rights reserved. 923 /// # 924 /// # The authors of the code are the authors of 925 /// # [draft-ietf-nfsv4-federated-fs-protocol-xx.txt]: J. Lentini, 926 /// # C. Everhart, D. Ellard, R. Tewari, and M. Naik. 927 /// # 928 /// # Redistribution and use in source and binary forms, with 929 /// # or without modification, are permitted provided that the 930 /// # following conditions are met: 931 /// # 932 /// # - Redistributions of source code must retain the above 933 /// # copyright notice, this list of conditions and the 934 /// # following disclaimer. 935 /// # 936 /// # - Redistributions in binary form must reproduce the above 937 /// # copyright notice, this list of conditions and the 938 /// # following disclaimer in the documentation and/or other 939 /// # materials provided with the distribution. 940 /// # 941 /// # - Neither the name of Internet Society, IETF or IETF 942 /// # Trust, nor the names of specific contributors, may be 943 /// # used to endorse or promote products derived from this 944 /// # software without specific prior written permission. 945 /// # 946 /// # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 947 /// # AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED 948 /// # WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 949 /// # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 950 /// # FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO 951 /// # EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 952 /// # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 953 /// # EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 954 /// # NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 955 /// # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 956 /// # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 957 /// # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 958 /// # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 959 /// # IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 960 /// # ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 961 /// # 963 965 4.2.1. LDAP Attributes 967 This section describes the required attributes of the NSDB LDAP 968 schema. The following definitions are used below: 970 o The "name" attribute described in [RFC4519]. 972 o The Integer syntax (1.3.6.1.4.1.1466.115.121.1.27) described in 973 [RFC4517]. 975 o The "integerMatch" rule described in [RFC4517]. 977 o The Octet String syntax (1.3.6.1.4.1.1466.115.121.1.40) described 978 in [RFC4517]. 980 o The "octetStringMatch" rule described in [RFC4517]. 982 o The Boolean syntax (1.3.6.1.4.1.1466.115.121.1.7) described in 983 [RFC4517]. 985 o The "booleanMatch" rule described in [RFC4517]. 987 o The "distinguishedNameMatch" rule described in [RFC4517]. 989 o The DN syntax (1.3.6.1.4.1.1466.115.121.1.12) described in 990 [RFC4517]. 992 o The "labeledURI" attribute described in [RFC2079]. 994 o The UUID syntax (1.3.6.1.1.16.1) described in [RFC4530]. 996 o The UuidMatch rule described in [RFC4530]. 998 o The UuidOrderingMatch rule described in [RFC4530]. 1000 4.2.1.1. fedfsUuid 1002 A fedfsUuid is the base type for all of the universally unique 1003 identifiers (UUIDs) used by the federated filesystem protocols. 1005 The fedfsUuid type is based on rules and syntax defined in [RFC4530]. 1007 A fedfsUuid is a single-valued LDAP attribute. 1009 1010 /// 1011 /// attributetype ( 1012 /// 1.3.6.1.4.1.31103.1.1 NAME 'fedfsUuid' 1013 /// DESC 'A UUID used by NSDB' 1014 /// EQUALITY uuidMatch 1015 /// ORDERING uuidOrderingMatch 1016 /// SYNTAX 1.3.6.1.1.16.1 1017 /// SINGLE-VALUE 1018 /// ) 1019 /// 1021 1023 4.2.1.2. fedfsFsnUuid 1025 A fedfsFsnUuid represents the UUID component of an FSN. An NSDB 1026 SHOULD ensure that no two FSNs it stores have the same fedfsFsnUuid. 1028 This attribute is single-valued. 1030 1032 /// 1033 /// attributetype ( 1034 /// 1.3.6.1.4.1.31103.1.4 NAME 'fedfsFsnUuid' 1035 /// DESC 'The FSN UUID component of an FSN' 1036 /// SUP fedfsUuid 1037 /// SINGLE-VALUE 1038 /// ) 1039 /// 1041 1043 4.2.1.3. fedfsFsnTTL 1045 A fedfsFsnTTL is the amount of time in seconds an FSN's TTL and its 1046 children FSL records SHOULD be cached by a fileserver. A fedfsFsnTTL 1047 MUST be encoded as an Integer syntax value [RFC4517]. 1049 This attribute is single-valued. 1051 1052 /// 1053 /// attributetype ( 1054 /// 1.3.6.1.4.1.31103.1.11 NAME 'fedfsFsnTTL' 1055 /// DESC 'Time to live of an FSN tree' 1056 /// EQUALITY integerMatch 1057 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1058 /// SINGLE-VALUE 1059 /// ) 1060 /// 1062 1064 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1066 4.2.1.4. fedfsNceDN 1068 A fedfsNceDN stores a distinguished name (DN). 1070 This attribute is single-valued. 1072 1074 /// 1075 /// attributetype ( 1076 /// 1.3.6.1.4.1.31103.1.14 NAME 'fedfsNceDN' 1077 /// DESC 'NCE Distinguished Name' 1078 /// EQUALITY distinguishedNameMatch 1079 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 1080 /// SINGLE-VALUE 1081 /// ) 1082 /// 1084 1086 OID 1.3.6.1.4.1.1466.115.121.1.12 is the DN syntax [RFC4517]. 1088 4.2.1.5. fedfsFslUuid 1090 A fedfsFslUuid represents the UUID of an FSL. An NSDB SHOULD ensure 1091 that no two FSLs it stores have the same fedfsFslUuid. 1093 This attribute is single-valued. 1095 1096 /// 1097 /// attributetype ( 1098 /// 1.3.6.1.4.1.31103.1.8 NAME 'fedfsFslUuid' 1099 /// DESC 'UUID of an FSL' 1100 /// SUP fedfsUuid 1101 /// SINGLE-VALUE 1102 /// ) 1103 /// 1105 1107 4.2.1.6. fedfsAnnotation 1109 A fedfsAnnotation contains an object annotation formatted as a key/ 1110 value pair. 1112 This attribute is multi-valued; an object type that permits 1113 annotations may have any number of annotations per instance. 1115 A fedfsAnnotation attribute is a human-readable sequence of UTF-8 1116 characters with no non-terminal NUL characters. The value MUST be 1117 formatted according to the following ABNF [RFC5234] rules: 1119 ANNOTATION = KEY EQUALS VALUE 1120 KEY = ITEM 1121 VALUE = ITEM 1122 ITEM = BLANK DQUOTE STR DQUOTE BLANK 1123 BLANK = 0*EMPTY 1124 EMPTY = SPACE / HTAB 1125 HTAB = %x09 ; horizontal tab 1126 STR = 0*UTF8 1128 The DQUOTE, EQUALS, UTF8, and SPACE rules are defined in [RFC4512]. 1130 The following escape sequences are allowed: 1132 +-----------------+-------------+ 1133 | escape sequence | replacement | 1134 +-----------------+-------------+ 1135 | \\ | \ | 1136 | \" | " | 1137 +-----------------+-------------+ 1139 A fedfsAnnotation value SHOULD be processed as follows: 1141 1. Parse the attribute value according to the ANNOTATION rule, 1142 ignoring the escape sequences above. 1144 2. Scan through results of the previous step and replace the escape 1145 sequences above. 1147 A fedfsAnnotation attribute that does not adhere to this format 1148 SHOULD be ignored. 1150 The following are examples of valid fedfsAnnotation attributes: 1152 "key1" = "foo" 1153 "another key" = "x=3" 1154 "key-2" = "A string with \" and \\ characters." 1156 which correspond to the following key/value pairs: 1158 +-------------+-----------------------------------+ 1159 | key | value | 1160 +-------------+-----------------------------------+ 1161 | key1 | foo | 1162 | another key | x=3 | 1163 | key-2 | A string with " and \ characters. | 1164 +-------------+-----------------------------------+ 1166 1168 /// 1169 /// attributetype ( 1170 /// 1.3.6.1.4.1.31103.1.12 NAME 'fedfsAnnotation' 1171 /// DESC 'Annotation of an object' 1172 /// SUP name 1173 /// ) 1174 /// 1176 1178 4.2.1.7. fedfsDescr 1180 A fedfsDescr stores an object description. The description MUST be 1181 encoded as a UTF-8 string. 1183 This attribute is multi-valued which permits any number of 1184 descriptions per entry. 1186 1187 /// 1188 /// attributetype ( 1189 /// 1.3.6.1.4.1.31103.1.13 NAME 'fedfsDescr' 1190 /// DESC 'Description of an object' 1191 /// SUP name 1192 /// ) 1193 /// 1195 1197 4.2.1.8. fedfsNfsURI 1199 A fedfsNfsURI stores the host and pathname components of an FSL. A 1200 fedfsNfsURI MUST be encoded as an NFS URI Section 2.8.1. 1202 The fedfsNfsURI is a subtype of the labeledURI type [RFC2079], with 1203 the same encoding rules. 1205 This attribute is single-valued. 1207 1209 /// 1210 /// attributetype ( 1211 /// 1.3.6.1.4.1.31103.1.120 NAME 'fedfsNfsURI' 1212 /// DESC 'Location of fileset' 1213 /// SUP labeledURI 1214 /// SINGLE-VALUE 1215 /// ) 1216 /// 1218 1220 4.2.1.9. fedfsNfsCurrency 1222 A fedfsNfsCurrency stores the NFSv4.1 fs_locations_server's 1223 fls_currency value [RFC5661]. A fedfsNfsCurrency MUST be encoded as 1224 an Integer syntax value [RFC4517] in the range [-2147483648, 1225 2147483647]. 1227 This attribute is single-valued. 1229 1230 /// 1231 /// attributetype ( 1232 /// 1.3.6.1.4.1.31103.1.103 NAME 'fedfsNfsCurrency' 1233 /// DESC 'up-to-date measure of the data' 1234 /// EQUALITY integerMatch 1235 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1236 /// SINGLE-VALUE 1237 /// ) 1238 /// 1240 1242 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1244 4.2.1.10. fedfsNfsGenFlagWritable 1246 A fedfsNfsGenFlagWritable stores the value of an FSL's NFSv4.1 1247 FSLI4GF_WRITABLE bit [RFC5661]. A value of "TRUE" indicates the bit 1248 is true. A value of "FALSE" indicates the bit is false. 1250 1252 /// 1253 /// attributetype ( 1254 /// 1.3.6.1.4.1.31103.1.104 NAME 'fedfsNfsGenFlagWritable' 1255 /// DESC 'Indicates if the filesystem is writable' 1256 /// EQUALITY booleanMatch 1257 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 1258 /// SINGLE-VALUE 1259 /// ) 1260 /// 1262 1264 OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517]. 1266 4.2.1.11. fedfsNfsGenFlagGoing 1268 A fedfsNfsGenFlagGoing stores the value of an FSL's NFSv4.1 1269 FSLI4GF_GOING bit [RFC5661]. A value of "TRUE" indicates the bit is 1270 true. A value of "FALSE" indicates the bit is false. 1272 1273 /// 1274 /// attributetype ( 1275 /// 1.3.6.1.4.1.31103.1.105 NAME 'fedfsNfsGenFlagGoing' 1276 /// DESC 'Indicates if the filesystem is going' 1277 /// EQUALITY booleanMatch 1278 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 1279 /// SINGLE-VALUE 1280 /// ) 1281 /// 1283 1285 OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517]. 1287 4.2.1.12. fedfsNfsGenFlagSplit 1289 A fedfsNfsGenFlagSplit stores the value of an FSL's NFSv4.1 1290 FSLI4GF_SPLIT bit [RFC5661]. A value of "TRUE" indicates the bit is 1291 true. A value of "FALSE" indicates the bit is false. 1293 1295 /// 1296 /// attributetype ( 1297 /// 1.3.6.1.4.1.31103.1.106 NAME 'fedfsNfsGenFlagSplit' 1298 /// DESC 'Indicates if there are multiple filesystems' 1299 /// EQUALITY booleanMatch 1300 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 1301 /// SINGLE-VALUE 1302 /// ) 1303 /// 1305 1307 OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517]. 1309 4.2.1.13. fedfsNfsTransFlagRdma 1311 A fedfsNfsTransFlagRdma stores the value of an FSL's NFSv4.1 1312 FSLI4TF_RDMA bit [RFC5661]. A value of "TRUE" indicates the bit is 1313 true. A value of "FALSE" indicates the bit is false. 1315 1316 /// 1317 /// attributetype ( 1318 /// 1.3.6.1.4.1.31103.1.107 NAME 'fedfsNfsTransFlagRdma' 1319 /// DESC 'Indicates if the transport supports RDMA' 1320 /// EQUALITY booleanMatch 1321 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 1322 /// SINGLE-VALUE 1323 /// ) 1324 /// 1326 1328 OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517]. 1330 4.2.1.14. fedfsNfsClassSimul 1332 A fedfsNfsClassSimul contains the FSL's NFSv4.1 FSLI4BX_CLSIMUL 1333 [RFC5661] value. A fedfsNfsClassSimul MUST be encoded as an Integer 1334 syntax value [RFC4517] in the range [0, 255]. 1336 1338 /// 1339 /// attributetype ( 1340 /// 1.3.6.1.4.1.31103.1.108 NAME 'fedfsNfsClassSimul' 1341 /// DESC 'The simultaneous-use class of the filesystem' 1342 /// EQUALITY integerMatch 1343 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1344 /// SINGLE-VALUE 1345 /// ) 1346 /// 1348 1350 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1352 4.2.1.15. fedfsNfsClassHandle 1354 A fedfsNfsClassHandle contains the FSL's NFSv4.1 FSLI4BX_CLHANDLE 1355 [RFC5661] value. A fedfsNfsClassHandle MUST be encoded as an Integer 1356 syntax value [RFC4517] in the range [0, 255]. 1358 1359 /// 1360 /// attributetype ( 1361 /// 1.3.6.1.4.1.31103.1.109 NAME 'fedfsNfsClassHandle' 1362 /// DESC 'The handle class of the filesystem' 1363 /// EQUALITY integerMatch 1364 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1365 /// SINGLE-VALUE 1366 /// ) 1367 /// 1369 1371 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1373 4.2.1.16. fedfsNfsClassFileid 1375 A fedfsNfsClassFileid contains the FSL's NFSv4.1 FSLI4BX_CLFILEID 1376 [RFC5661] value. A fedfsNfsClassFileid MUST be encoded as an Integer 1377 syntax value [RFC4517] in the range [0, 255]. 1379 1381 /// 1382 /// attributetype ( 1383 /// 1.3.6.1.4.1.31103.1.110 NAME 'fedfsNfsClassFileid' 1384 /// DESC 'The fileid class of the filesystem' 1385 /// EQUALITY integerMatch 1386 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1387 /// SINGLE-VALUE 1388 /// ) 1389 /// 1391 1393 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1395 4.2.1.17. fedfsNfsClassWritever 1397 A fedfsNfsClassWritever contains the FSL's NFSv4.1 FSLI4BX_CLWRITEVER 1398 [RFC5661] value. A fedfsNfsClassWritever MUST be encoded as an 1399 Integer syntax value [RFC4517] in the range [0, 255]. 1401 1402 /// 1403 /// attributetype ( 1404 /// 1.3.6.1.4.1.31103.1.111 NAME 'fedfsNfsClassWritever' 1405 /// DESC 'The write-verifier class of the filesystem' 1406 /// EQUALITY integerMatch 1407 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1408 /// SINGLE-VALUE 1409 /// ) 1410 /// 1412 1414 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1416 4.2.1.18. fedfsNfsClassChange 1418 A fedfsNfsClassChange contains the FSL's NFSv4.1 FSLI4BX_CLCHANGE 1419 [RFC5661] value. A fedfsNfsClassChange MUST be encoded as an Integer 1420 syntax value [RFC4517] in the range [0, 255]. 1422 1424 /// 1425 /// attributetype ( 1426 /// 1.3.6.1.4.1.31103.1.112 NAME 'fedfsNfsClassChange' 1427 /// DESC 'The change class of the filesystem' 1428 /// EQUALITY integerMatch 1429 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1430 /// SINGLE-VALUE 1431 /// ) 1432 /// 1434 1436 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1438 4.2.1.19. fedfsNfsClassReaddir 1440 A fedfsNfsClassReaddir contains the FSL's NFSv4.1 FSLI4BX_CLREADDIR 1441 [RFC5661] value. A fedfsNfsClassReaddir MUST be encoded as an 1442 Integer syntax value [RFC4517] in the range [0, 255]. 1444 1445 /// 1446 /// attributetype ( 1447 /// 1.3.6.1.4.1.31103.1.113 NAME 'fedfsNfsClassReaddir' 1448 /// DESC 'The readdir class of the filesystem' 1449 /// EQUALITY integerMatch 1450 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1451 /// SINGLE-VALUE 1452 /// ) 1453 /// 1455 1457 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1459 4.2.1.20. fedfsNfsReadRank 1461 A fedfsNfsReadRank contains the FSL's NFSv4.1 FSLI4BX_READRANK 1462 [RFC5661] value. A fedfsNfsReadRank MUST be encoded as an Integer 1463 syntax value [RFC4517] in the range [0, 255]. 1465 1467 /// 1468 /// attributetype ( 1469 /// 1.3.6.1.4.1.31103.1.114 NAME 'fedfsNfsReadRank' 1470 /// DESC 'The read rank of the filesystem' 1471 /// EQUALITY integerMatch 1472 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1473 /// SINGLE-VALUE 1474 /// ) 1475 /// 1477 1479 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1481 4.2.1.21. fedfsNfsReadOrder 1483 A fedfsNfsReadOrder contains the FSL's NFSv4.1 FSLI4BX_READORDER 1484 [RFC5661] value. A fedfsNfsReadOrder MUST be encoded as an Integer 1485 syntax value [RFC4517] in the range [0, 255]. 1487 1488 /// 1489 /// attributetype ( 1490 /// 1.3.6.1.4.1.31103.1.115 NAME 'fedfsNfsReadOrder' 1491 /// DESC 'The read order of the filesystem' 1492 /// EQUALITY integerMatch 1493 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1494 /// SINGLE-VALUE 1495 /// ) 1496 /// 1498 1500 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1502 4.2.1.22. fedfsNfsWriteRank 1504 A fedfsNfsWriteRank contains the FSL's FSLI4BX_WRITERANK [RFC5661] 1505 value. A fedfsNfsWriteRank MUST be encoded as an Integer syntax 1506 value [RFC4517] in the range [0, 255]. 1508 1510 /// 1511 /// attributetype ( 1512 /// 1.3.6.1.4.1.31103.1.116 NAME 'fedfsNfsWriteRank' 1513 /// DESC 'The write rank of the filesystem' 1514 /// EQUALITY integerMatch 1515 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1516 /// SINGLE-VALUE 1517 /// ) 1518 /// 1520 1522 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1524 4.2.1.23. fedfsNfsWriteOrder 1526 A fedfsNfsWriteOrder contains the FSL's FSLI4BX_WRITEORDER [RFC5661] 1527 value. A fedfsNfsWriteOrder MUST be encoded as an Integer syntax 1528 value [RFC4517] in the range [0, 255]. 1530 1531 /// 1532 /// attributetype ( 1533 /// 1.3.6.1.4.1.31103.1.117 NAME 'fedfsNfsWriteOrder' 1534 /// DESC 'The write order of the filesystem' 1535 /// EQUALITY integerMatch 1536 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1537 /// SINGLE-VALUE 1538 /// ) 1539 /// 1541 1543 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1545 4.2.1.24. fedfsNfsVarSub 1547 A fedfsNfsVarSub stores the value of an FSL's NFSv4.1 FSLI4F_VAR_SUB 1548 bit [RFC5661]. A value of "TRUE" indicates the bit is true. A value 1549 of "FALSE" indicates the bit is false. 1551 1553 /// 1554 /// attributetype ( 1555 /// 1.3.6.1.4.1.31103.1.118 NAME 'fedfsNfsVarSub' 1556 /// DESC 'Indicates if variable substitution is present' 1557 /// EQUALITY booleanMatch 1558 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 1559 /// SINGLE-VALUE 1560 /// ) 1561 /// 1563 1565 OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517]. 1567 4.2.1.25. fedfsNfsValidFor 1569 A fedfsNfsValidFor stores an FSL's NFSv4.1 fs_locations_info 1570 fli_valid_for value [RFC5661]. A fedfsNfsValidFor MUST be encoded as 1571 an Integer syntax value [RFC4517] in the range [-2147483648, 1572 2147483647]. 1574 An FSL's parent's fedfsFsnTTL value and its fedfsNfsValidFor value 1575 MAY be different. 1577 This attribute is single-valued. 1579 1581 /// 1582 /// attributetype ( 1583 /// 1.3.6.1.4.1.31103.1.19 NAME 'fedfsNfsValidFor' 1584 /// DESC 'Valid for time' 1585 /// EQUALITY integerMatch 1586 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1587 /// SINGLE-VALUE 1588 /// ) 1589 /// 1591 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1593 1595 4.2.2. LDAP Objects 1597 4.2.2.1. fedfsNsdbContainerInfo 1599 A fedfsNsdbContainerInfo describes the location of the NCE. 1601 A fedfsFsn's fedfsNceDN attribute is REQUIRED. 1603 A fedfsFsn's fedfsAnnotation and fedfsDescr attributes are OPTIONAL. 1605 1607 /// 1608 /// objectclass ( 1609 /// 1.3.6.1.4.1.31103.1.1001 NAME 'fedfsNsdbContainerInfo' 1610 /// DESC 'Describes NCE location' 1611 /// SUP top AUXILIARY 1612 /// MUST ( 1613 /// fedfsNceDN 1614 /// ) 1615 /// MAY ( 1616 /// fedfsAnnotation 1617 /// $ fedfsDescr 1618 /// )) 1619 /// 1621 1623 4.2.2.2. fedfsFsn 1625 A fedfsFsn represents an FSN. 1627 A fedfsFsn's fedfsFsnUuid and fedfsFsnTTL attributes are REQUIRED. 1629 A fedfsFsn's fedfsAnnotation and fedfsDescr attributes are OPTIONAL. 1631 The DN of an FSN is REQUIRED to take the following form: 1632 "fedfsFsnUuid=$FSNUUID,$NCE", where $FSNUUID is the UUID of the FSN 1633 and $NCE is the DN of the NCE. Since LDAP requires a DN to be 1634 unique, this ensures that each FSN entry has a unique UUID value 1635 within the LDAP directory. 1637 A fedfsFsn MAY also have additional attributes, but these attributes 1638 MUST NOT be referenced by any part of this document. 1640 1642 /// 1643 /// objectclass ( 1644 /// 1.3.6.1.4.1.31103.1.1002 NAME 'fedfsFsn' 1645 /// DESC 'Represents a fileset' 1646 /// SUP top STRUCTURAL 1647 /// MUST ( 1648 /// fedfsFsnUuid 1649 /// $ fedfsFsnTTL 1650 /// ) 1651 /// MAY ( 1652 /// fedfsAnnotation 1653 /// $ fedfsDescr 1654 /// )) 1655 /// 1657 1659 4.2.2.3. fedfsFsl 1661 The fedfsFsl object class represents an FSL. 1663 The fedfsFsl is an abstract object class. Protocol specific subtypes 1664 of this object class are used to store FSL information. The 1665 fedfsNfsFsl object class defined below is used to record an NFS FSL's 1666 location. Other subtypes MAY be defined for other protocols (e.g., 1667 CIFS). 1669 A fedfsFsl's fedfsFslUuid and fedfsFsnUuid attributes are REQUIRED. 1671 A fedfsFsl's fedfsAnnotation, and fedfsDescr attributes are OPTIONAL. 1673 The DN of an FSL is REQUIRED to take the following form: 1674 "fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE" where $FSLUUID is 1675 the FSL's UUID, $FSNUUID is the FSN's UUID, and $NCE is the DN of the 1676 NCE. Since LDAP requires a DN to be unique, this ensures that each 1677 FSL entry has a unique UUID value within the LDAP directory. 1679 1681 /// 1682 /// objectclass ( 1683 /// 1.3.6.1.4.1.31103.1.1003 NAME 'fedfsFsl' 1684 /// DESC 'A physical location of a fileset' 1685 /// SUP top ABSTRACT 1686 /// MUST ( 1687 /// fedfsFslUuid 1688 /// $ fedfsFsnUuid 1689 /// ) 1690 /// MAY ( 1691 /// fedfsAnnotation 1692 /// $ fedfsDescr 1693 /// )) 1694 /// 1696 1698 4.2.2.4. fedfsNfsFsl 1700 A fedfsNfsFsl is used to represent an NFS FSL. The fedfsNfsFsl 1701 inherits all of the attributes of the fedfsFsl and extends the 1702 fedfsFsl with information specific to the NFS protocol. 1704 The DN of an NFS FSL is REQUIRED to take the following form: 1705 "fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE" where $FSLUUID is 1706 the FSL's UUID, $FSNUUID is the FSN's UUID, and $NCE is the DN of the 1707 NCE. Since LDAP requires a DN to be unique, this ensures that each 1708 NFS FSL entry has a unique UUID value within the LDAP directory. 1710 1711 /// 1712 /// objectclass ( 1713 /// 1.3.6.1.4.1.31103.1.1004 NAME 'fedfsNfsFsl' 1714 /// DESC 'An NFS location of a fileset' 1715 /// SUP fedfsFsl STRUCTURAL 1716 /// MUST ( 1717 /// fedfsNfsURI 1718 /// $ fedfsNfsCurrency 1719 /// $ fedfsNfsGenFlagWritable 1720 /// $ fedfsNfsGenFlagGoing 1721 /// $ fedfsNfsGenFlagSplit 1722 /// $ fedfsNfsTransFlagRdma 1723 /// $ fedfsNfsClassSimul 1724 /// $ fedfsNfsClassHandle 1725 /// $ fedfsNfsClassFileid 1726 /// $ fedfsNfsClassWritever 1727 /// $ fedfsNfsClassChange 1728 /// $ fedfsNfsClassReaddir 1729 /// $ fedfsNfsReadRank 1730 /// $ fedfsNfsReadOrder 1731 /// $ fedfsNfsWriteRank 1732 /// $ fedfsNfsWriteOrder 1733 /// $ fedfsNfsVarSub 1734 /// $ fedfsNfsValidFor 1735 /// )) 1736 /// 1738 1740 5. NSDB Operations 1742 The operations defined by the protocol can be described as several 1743 sub-protocols that are used by entities within a federation to 1744 perform different roles. 1746 The first of these sub-protocols defines how the state of an NSDB 1747 node can be initialized and updated. The primary use of this sub- 1748 protocol is by an administrator to add, edit, or delete filesets, 1749 their properties, and their fileset locations. 1751 The second of these sub-protocols defines the queries that are sent 1752 to an NSDB node in order to perform resolution (or to find other 1753 information about the data stored within that NSDB node) and the 1754 responses returned by the NSDB node. The primary use of this sub- 1755 protocol is by a fileserver in order to perform resolution, but it 1756 may also be used by an administrator to query the state of the 1757 system. 1759 The first and second sub-protocols are defined as LDAP operations, 1760 using the schema defined in the previous section. If each NSDB node 1761 is a standard LDAP server, then, in theory, it is unnecessary to 1762 describe the LDAP operations in detail, because the operations are 1763 ordinary LDAP operations to query and update records. However, we do 1764 not require that an NSDB node implement a complete LDAP service, and 1765 therefore we define in these sections the minimum level of LDAP 1766 functionality required to implement an NSDB node. 1768 The NSDB sub-protocols are defined in the next two sub-sections. The 1769 descriptions of LDAP messages in these sections use the LDAP Data 1770 Interchange Format (LDIF) [RFC2849]. In order to differentiate 1771 constant and variable strings in the LDIF specifications, variables 1772 are prefixed by a $ character and use all upper case characters. For 1773 example, a variable named FOO would be specified as $FOO. 1775 This document uses the term NSDB client to refer to an LDAP client 1776 that uses either of the NSDB sub-protocols. 1778 The third sub-protocol defines the queries and other requests that 1779 are sent to a fileserver in order to get information from it or to 1780 modify the state of the fileserver in a manner related to the 1781 federation protocols. The primary purpose of this protocol is for an 1782 administrator to create or delete a junction or discover related 1783 information about a particular fileserver. 1785 The third sub-protocol is defined as an ONC RPC protocol. The reason 1786 for using ONC RPC instead of LDAP is that all fileservers support ONC 1787 RPC but some do not support an LDAP Directory server. 1789 The ONC RPC administration protocol is defined in [FEDFS-ADMIN]. 1791 5.1. NSDB Operations for Administrators 1793 The admin entity initiates and controls the commands to manage 1794 fileset and namespace information. The protocol used for 1795 communicating between the admin entity and each NSDB node MUST be the 1796 LDAPv3 [RFC4510] protocol. 1798 The names we assign to these operations are entirely for the purpose 1799 of exposition in this document, and are not part of the LDAP dialogs. 1801 5.1.1. Create an FSN 1803 This operation creates a new FSN in the NSDB by adding a new fedfsFsn 1804 entry in the NSDB's LDAP directory. 1806 A fedfsFsn entry contains a fedfsFsnUuid. The administrator chooses 1807 the fedfsFsnUuid by a process described in Section 2.12). A fedfsFsn 1808 entry also contains a fedfsFsnTTL. The fedfsFsnTTL is chosen by the 1809 administrator as described in Section 2.8.3. 1811 The NSDB node that receives the request SHOULD check all of the 1812 attributes for validity and consistency, but this is not generally 1813 possible for LDAP servers because the consistency requirements cannot 1814 be expressed in the LDAP schema (although many LDAP servers can be 1815 extended, via plug-ins or other mechanisms, to add functionality 1816 beyond the strict definition of LDAP). 1818 5.1.1.1. LDAP Request 1820 This operation is implemented using the LDAP ADD request described by 1821 the LDIF below. 1823 dn: fedfsFsnUuid=$FSNUUID,$NCE 1824 changeType: add 1825 objectClass: fedfsFsn 1826 fedfsFsnUuid: $FSNUUID 1827 fedfsFsnTTL: $TTL 1829 For example, if the $FSNUUID is "e8c4761c-eb3b-4307-86fc- 1830 f702da197966", the $TTL is "300" seconds, and the $NCE is "o=fedfs" 1831 the operation would be: 1833 dn: fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs 1834 changeType: add 1835 objectClass: fedfsFsn 1836 fedfsFsnUuid: e8c4761c-eb3b-4307-86fc-f702da197966 1837 fedfsFsnTTL: 300 1839 5.1.2. Delete an FSN 1841 This operation deletes an FSN by removing a fedfsFsn entry in the 1842 NSDB's LDAP directory. 1844 If the FSN entry being deleted has child FSL entries, this function 1845 MUST return an error. This ensures that the NSDB will not contain 1846 any orphaned FSL entries. A compliant LDAP implementation will meet 1847 this requirement since Section 4.8 of [RFC4511] defines the LDAP 1848 delete operation to only be capable of removing leaf entries. 1850 Note that the FSN delete function removes the fileset only from a 1851 federation namespace (by removing the records for that FSN from the 1852 NSDB node that receives this request). The fileset and its data are 1853 not deleted. Any junction that has this FSN as its target may 1854 continue to point to this non-existent FSN. A dangling reference may 1855 be detected when a fileserver tries to resolve a junction that refers 1856 to the deleted FSN. 1858 5.1.2.1. LDAP Request 1860 This operation is implemented using the LDAP DELETE request described 1861 by the LDIF below. 1863 dn: fedfsFsnUuid=$FSNUUID,$NCE 1864 changeType: delete 1866 For example, if the $FSNUUID is "e8c4761c-eb3b-4307-86fc- 1867 f702da197966" and $NCE is "o=fedfs", the operation would be: 1869 dn: fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs 1870 changeType: delete 1872 5.1.3. Create an FSL 1874 This operation creates a new FSL for the given FSN by adding a new 1875 fedfsFsl entry in the NSDB's LDAP directory. 1877 A fedfsFsl entry contains a fedfsFslUuid and fedfsFsnUuid. The 1878 administrator chooses the fedfsFslUuid. The process for choosing the 1879 fedfsFslUuid is described in Section 2.12. The fedfsFsnUuid is the 1880 UUID of the FSL's FSN. 1882 The administrator will also set additional attributes depending on 1883 the FSL type. 1885 5.1.3.1. LDAP Request 1887 This operation is implemented using the LDAP ADD request described by 1888 the LDIF below (NOTE: the LDIF shows the creation of an NFS FSL) 1889 dn: fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE 1890 changeType: add 1891 objectClass: fedfsNfsFsl 1892 fedfsFslUuid: $FSLUUID 1893 fedfsFsnUuid: $FSNUUID 1894 fedfsNfsURI: nfs://$HOST:$PORT//$PATH 1895 fedfsNfsCurrency: $CURRENCY 1896 fedfsNfsGenFlagWritable: $WRITABLE 1897 fedfsNfsGenFlagGoing: $GOING 1898 fedfsNfsGenFlagSplit: $SPLIT 1899 fedfsNfsTransFlagRdma: $RDMA 1900 fedfsNfsClassSimul: $CLASS_SIMUL 1901 fedfsNfsClassHandle:$CLASS_HANDLE 1902 fedfsNfsClassFileid:$CLASS_FILEID 1903 fedfsNfsClassWritever:$CLASS_WRITEVER 1904 fedfsNfsClassChange: $CLASS_CHANGE 1905 fedfsNfsClassReaddir: $CLASS_READDIR 1906 fedfsNfsReadRank: $READ_RANK 1907 fedfsNfsReadOrder: $READ_ORDER 1908 fedfsNfsWriteRank: $WRITE_RANK 1909 fedfsNfsWriteOrder: $WRITE_ORDER 1910 fedfsNfsVarSub: $VAR_SUB 1911 fedfsNfsValidFor: $TIME 1912 fedfsAnnotation: $ANNOTATION 1913 fedfsDescr: $DESCR 1915 For example, if the $FSNUUID is "e8c4761c-eb3b-4307-86fc- 1916 f702da197966", the $FSLUUID is "ba89a802-41a9-44cf-8447- 1917 dda367590eb3", the $HOST is "server.example.com", $PORT is "2049", 1918 the $PATH is stored in the file "/tmp/fsl_path", $CURRENCY is "0" (an 1919 up to date copy), the FSL is writable, but not going, split, or 1920 accessible via RDMA, the simultaneous-use class is "1", the handle 1921 class is "0", the fileid class is "1", the write-verifier class is 1922 "1", the change class is "1", the readdir class is "9", the read rank 1923 is "7", the read order is "8", the write rank is "5", the write order 1924 is "6", variable substitution is false, $TIME is "300" seconds, 1925 $ANNOTATION is ""foo" = "bar"", $DESC is "This is a description.", 1926 and the $NCE is "o=fedfs", the operation would be (for readability 1927 the DN is split into two lines): 1929 dn: fedfsFslUuid=ba89a802-41a9-44cf-8447-dda367590eb3, 1930 fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs 1931 changeType: add 1932 objectClass: fedfsNfsFsl 1933 fedfsFslUuid: ba89a802-41a9-44cf-8447-dda367590eb3 1934 fedfsFsnUuid: e8c4761c-eb3b-4307-86fc-f702da197966 1935 fedfsNfsURI: nfs://server.example.com//tmp/fsl_path 1936 fedfsNfsCurrency: 0 1937 fedfsNfsGenFlagWritable: TRUE 1938 fedfsNfsGenFlagGoing: FALSE 1939 fedfsNfsGenFlagSplit: FALSE 1940 fedfsNfsTransFlagRdma: FALSE 1941 fedfsNfsClassSimul: 1 1942 fedfsNfsClassHandle: 0 1943 fedfsNfsClassFileid: 1 1944 fedfsNfsClassWritever: 1 1945 fedfsNfsClassChange: 1 1946 fedfsNfsClassReaddir: 9 1947 fedfsNfsReadRank: 7 1948 fedfsNfsReadOrder: 8 1949 fedfsNfsWriteRank: 5 1950 fedfsNfsWriteOrder: 6 1951 fedfsNfsVarSub: FALSE 1952 fedfsNfsValidFor: 300 1953 fedfsAnnotation: "foo" = "bar" 1954 fedfsDescr: This is a description. 1956 5.1.3.2. Selecting fedfsNfsFsl Values 1958 The fedfsNfsFSl object class is used to describe NFSv4 accessible 1959 filesets. For the reasons described in Section 2.8.4, administrators 1960 SHOULD choose reasonable values for all LDAP attributes of an NFSv4 1961 accessible fedfsNfsFsl even though some of these LDAP attributes are 1962 not explicitly contained in an NFSv4 fs_locations attribute. 1964 When the administrator is unable to choose reasonable values for the 1965 LDAP attributes not explicitly contained in a NFSv4 fs_locations 1966 attribute, the values in the following table are RECOMMENDED. 1968 +-------------------------+----------+------------------------------+ 1969 | LDAP attribute | LDAP | Notes | 1970 | | value | | 1971 +-------------------------+----------+------------------------------+ 1972 | fedfsNfsCurrency | negative | Indicates that the server | 1973 | | value | does not know the currency | 1974 | | | (see 11.10.1 of [RFC5661]). | 1975 | fedfsNfsGenFlagWritable | FALSE | Leaving unset is not harmful | 1976 | | | (see 11.10.1 of [RFC5661]). | 1977 | fedfsNfsGenFlagGoing | FALSE | NFS client will detect a | 1978 | | | migration event if the FSL | 1979 | | | becomes unavailable. | 1980 | fedfsNfsGenFlagSplit | TRUE | Safe to assume that the FSL | 1981 | | | is split. | 1982 | fedfsNfsTransFlagRdma | TRUE | NFS client will detect if | 1983 | | | RDMA access is available. | 1984 | fedfsNfsClassSimul | 0 | 0 is treated as non-matching | 1985 | | | (see 11.10.1 of [RFC5661]). | 1986 | fedfsNfsClassHandle | 0 | See fedfsNfsClassSimul note. | 1987 | fedfsNfsClassFileid | 0 | See fedfsNfsClassSimul note. | 1988 | fedfsNfsClassWritever | 0 | See fedfsNfsClassSimul note. | 1989 | fedfsNfsClassChange | 0 | See fedfsNfsClassSimul note. | 1990 | fedfsNfsClassReaddir | 0 | See fedfsNfsClassSimul note. | 1991 | fedfsNfsReadRank | 0 | Highest value ensures FSL | 1992 | | | will be tried. | 1993 | fedfsNfsReadOrder | 0 | See fedfsNfsReadRank note. | 1994 | fedfsNfsWriteRank | 0 | See fedfsNfsReadRank note. | 1995 | fedfsNfsWriteOrder | 0 | See fedfsNfsReadRank note. | 1996 | fedfsNfsVarSub | FALSE | NFSv4 does not define | 1997 | | | variable substituion in | 1998 | | | paths. | 1999 | fedfsNfsValidFor | 0 | Indicates no appropriate | 2000 | | | refetch interval (see | 2001 | | | 11.10.2 of [RFC5661]). | 2002 +-------------------------+----------+------------------------------+ 2004 5.1.4. Delete an FSL 2006 This operation deletes a Fileset location record. The admin requests 2007 the NSDB node storing the fedfsFsl to delete it from its database. 2008 This operation does not result in fileset data being deleted on any 2009 fileserver. 2011 5.1.4.1. LDAP Request 2013 The admin sends an LDAP DELETE request to the NSDB node to remove the 2014 FSL. 2016 dn: fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE 2017 changeType: delete 2019 For example, if the $FSNUUID is "e8c4761c-eb3b-4307-86fc- 2020 f702da197966", the $FSLUUID is "ba89a802-41a9-44cf-8447- 2021 dda367590eb3", and the $NCE is "o=fedfs", the operation would be (for 2022 readability the DN is split into two lines): 2024 dn: fedfsFslUuid=ba89a802-41a9-44cf-8447-dda367590eb3, 2025 fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs 2026 changeType: delete 2028 5.1.5. Update an FSL 2030 This operation updates the attributes of a given FSL. This command 2031 results in a change in the attributes of the fedfsFsl at the NSDB 2032 node maintaining this FSL. The attributes that must not change are 2033 the fedfsFslUuid and the fedfsFsnUuid of the fileset this FSL 2034 implements. 2036 5.1.5.1. LDAP Request 2038 The admin sends an LDAP MODIFY request to the NSDB node to update the 2039 FSL. 2041 dn: fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE 2042 changeType: modify 2043 replace: $ATTRIBUTE-TYPE 2045 For example, if the $FSNUUID is "e8c4761c-eb3b-4307-86fc- 2046 f702da197966", the $FSLUUID is "ba89a802-41a9-44cf-8447- 2047 dda367590eb3", the $NCE is "o=fedfs", and the administrator wished to 2048 change the NFS read rank to 10, the operation would be (for 2049 readability the DN is split into two lines): 2051 dn: fedfsFslUuid=ba89a802-41a9-44cf-8447-dda367590eb3, 2052 fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs 2053 changeType: modify 2054 replace: fedfsNfsReadClass 2055 fedfsNfsReadRank: 10 2057 5.2. NSDB Operations for Fileservers 2059 5.2.1. NSDB Container Entry (NCE) Enumeration 2061 To find the NCEs for the NSDB nsdb.example.com, a fileserver would do 2062 the following: 2064 nce_list = empty 2065 connect to the LDAP directory at nsdb.example.com 2066 for each namingContext value $BAR in the root DSE 2067 /* $BAR is a DN */ 2068 query for a fedfsNceDN value at $BAR 2069 /* 2070 * The RFC 4516 LDAP URL for this search would be 2071 * 2072 * ldap://nsdb.example.com:389/$BAR?fedfsNceDN?? 2073 * (objectClass=fedfsNsdbContainerInfo) 2074 * 2075 */ 2076 if a fedfsNceDN value is found 2077 add the value to the nce_list 2079 5.2.2. Lookup FSLs for an FSN 2081 Using an LDAP search, the fileserver can obtain all of the FSLs for a 2082 given FSN. The FSN's fedfsFsnUuid is used as the search key. The 2083 following examples use the LDAP Universal Resource Identifier (URI) 2084 format defined in [RFC4516]. 2086 To obtain a list of all FSLs for $FSNUUID on the NSDB named 2087 $NSDBNAME, the following search can be used (for readability the URI 2088 is split into two lines): 2090 for each $NCE in nce_list 2091 ldap://$NSDBNAME/fsnUuid=$FSNUUID,$NCE??one? 2092 (objectClass=fedfsFsl) 2094 This search is for the children of the object with DN 2095 "fedfsFsnUuid=$FSNUUID,$NCE" with a filter for 2096 "objectClass=fedfsFsl". The scope value of "one" restricts the 2097 search to the entry's children (rather than the entire subtree below 2098 the entry) and the filter ensures that only FSL entries are returned. 2100 For example if $NSDBNAME is "nsdb.example.com", $FSNUUID is 2101 "e8c4761c-eb3b-4307-86fc-f702da197966", and $NCE is "o=fedfs", the 2102 search would be (for readability the URI is split into three lines): 2104 ldap://nsdb.example.com/ 2105 fsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs 2106 ??one?(objectClass=fedfsFsl) 2108 The following search can be used to obtain only the NFS FSLs for 2109 $FSNUUID on the NSDB named $NSDBNAME (for readability the URI is 2110 split into two lines): 2112 for each $NCE in nce_list 2113 ldap://$NSDBNAME/fsnUuid=$FSNUUID,$NCE??one? 2114 (objectClass=fedfsNfsFsl) 2116 This also searches for the children of the object with DN 2117 "fedfsFsnUuid=$FSNUUID,$NCE", but the filter for "objectClass = 2118 fedfsNfsFsl" restricts the results to only NFS FSLs. 2120 For example if $NSDBNAME is nsdb.example.com, $FSNUUID is "e8c4761c- 2121 eb3b-4307-86fc-f702da197966", and $NCE is "o=fedfs",the search would 2122 be (for readability the URI is split into three lines): 2124 ldap://nsdb.example.com/ 2125 fsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs 2126 ??one?(objectClass=fedfsNfsFsl) 2128 The fileserver will generate a referral based on the set of FSLs 2129 returned by these queries using the process described in 2130 Section 2.8.4. 2132 5.3. NSDB Operations and LDAP Referrals 2134 The LDAPv3 protocol defines an LDAP referral mechanism that allows an 2135 LDAP server to redirect an LDAP client. LDAPv3 defines two types of 2136 LDAP referrals: the Referral type defined in Section 4.1.10 of 2137 [RFC4511] and the SearchResultReference type defined in Section 4.5.3 2138 of [RFC4511]. In both cases, the LDAP referral lists one or more 2139 URIs for services that can be used to complete the operation. In the 2140 remainder of this document, the term LDAP referral is used to 2141 indicate either of these types. 2143 If an NSDB operation results in an LDAP referral, the NSDB client MAY 2144 follow the LDAP referral. An NSDB client's decision to follow an 2145 LDAP referral is implementation and configuration dependent. For 2146 example, an NSDB client might be configured to follow only those LDAP 2147 referrals that were received over a secure channel, or only those 2148 that target an NSDB that supports encrypted communication. If an 2149 NSDB client chooses to follow an LDAP referral, the NSDB client MUST 2150 process the LDAP referral and prevent looping as described in Section 2151 4.1.10 of [RFC4511]. 2153 6. Security Considerations 2155 Both the NFSv4 and LDAPv3 protocols provide security mechanisms. 2156 When used in conjunction with the federated filesystem protocols 2157 described in this document, the use of these mechanisms is 2158 RECOMMENDED. Specifically, the use of RPCSEC_GSS [RFC2203], which is 2159 built on the GSS-API [RFC2743], is RECOMMENDED on all NFS connections 2160 between a file-access client and fileserver. The "Security 2161 Considerations" sections of the NFSv4.0 [3530bis] and NFSv4.1 2162 [RFC5661] specifications contain special considerations for the 2163 handling of GETATTR operations for the fs_locations and 2164 fs_locations_info attributes. For all LDAP connections established 2165 by the federated filesystem protocols, the use of TLS [RFC5246], as 2166 described in [RFC4513], is RECOMMENDED. 2168 If an NSDB client chooses to follow an LDAP referral, the NSDB client 2169 SHOULD authenticate the LDAP referral's target NSDB using the target 2170 NSDB's credentials (not the credentials of the NSDB that generated 2171 the LDAP referral). The NSDB client SHOULD NOT follow an LDAP 2172 referral that targets an NSDB for which it does not know the NSDB's 2173 credentials. 2175 Within a federation, there are two types of components an attacker 2176 may compromise: a fileserver and an NSDB. 2178 If an attacker compromises a fileserver, the attacker can interfere 2179 with a file-access client's filesystem I/O operations (e.g., by 2180 returning fictitious data in the response to a read request) or 2181 fabricating a referral. The attacker's abilities are the same 2182 regardless of whether or not the federation protocols are in use. 2183 While the federation protocols do not give the attacker additional 2184 capabilities, they are additional targets for attack. The LDAP 2185 protocol described in Section 5.2 SHOULD be secured using the methods 2186 described above to defeat attacks on a fileserver via this channel. 2188 If an attacker compromises an NSDB, the attacker will be able to 2189 forge FSL information and thus poison the fileserver's referral 2190 information. Therefore an NSDB should be as secure as the 2191 fileservers which query it. The LDAP operations described in 2192 Section 5 SHOULD be secured using the methods described above to 2193 defeat attacks on an NSDB via this channel. 2195 A fileserver binds anonymously when performing NSDB operations. Thus 2196 the contents and distinguished names of FSN and FSL records are 2197 required to be readable by anyone who can bind anonymously to an NSDB 2198 service. Section 2.12 presents the security considerations in the 2199 choice of the type of UUID used in these records. 2201 It should be noted that the federation protocols do not directly 2202 provide access to filesystem data. The federation protocols only 2203 provide a mechanism for building a namespace. All data transfers 2204 occur between a file-access client and fileserver just as they would 2205 if the federation protocols were not in use. As a result, the 2206 federation protocols do not require new user authentication and 2207 authorization mechanisms or require a fileserver to act as a proxy 2208 for a client. 2210 7. IANA Considerations 2212 7.1. Registry for the fedfsAnnotation Key Namespace 2214 This document defines the fedfsAnnotation key in Section 4.2.1.6. 2215 The fedfsAnnotation key namespace is to be managed by IANA. IANA is 2216 to create and maintain a new registry entitled "FedFS Annotation 2217 Keys". Future registrations are to be administered by IANA using the 2218 "First Come First Served" policy defined in [RFC5226]. Registration 2219 requests MUST include the key (a valid UTF-8 string of any length), a 2220 brief description of the key's purpose, and an email contact for the 2221 registration. For viewing, the registry should be sorted 2222 lexicographically by key. There are no initial assignments for this 2223 registry. 2225 7.2. Registry for FedFS Object Identifiers 2227 Using the process described in [RFC2578], one of the authors was 2228 assigned the Internet Private Enterprise Numbers range 2229 1.3.6.1.4.1.31103.x. Within this range, the subrange 2230 1.3.6.1.4.1.31103.1.x is permanently dedicated for use by the 2231 federated file system protocols. 2233 IANA is to create and maintain a new registry entitled "FedFS Object 2234 Identifiers" for the purpose of administering the FedFS Object 2235 Identifier (OID) range. Future allocations from the 2236 1.3.6.1.4.1.31103.1.x range are to be assigned by IANA using the "RFC 2237 Required" policy defined in [RFC5226]. Registration requests MUST 2238 include an OID value from the 1.3.6.1.4.1.31103.1.x range, a short 2239 description of the OID, and a reference to the specification that 2240 defines the OID's usage. For viewing, the registry should be sorted 2241 numerically by OID value. The initial contents of the FedFS Object 2242 Identifiers registry are given in Table 1. 2244 +--------------------------+-------------------------+------------+ 2245 | OID | Description | Reference | 2246 +--------------------------+-------------------------+------------+ 2247 | 1.3.6.1.4.1.31103.1.1 | fedfsUuid | RFC-TBD1 | 2248 | 1.3.6.1.4.1.31103.1.2 | fedfsNetAddr | deprecated | 2249 | 1.3.6.1.4.1.31103.1.3 | fedfsNetPort | deprecated | 2250 | 1.3.6.1.4.1.31103.1.4 | fedfsFsnUuid | RFC-TBD1 | 2251 | 1.3.6.1.4.1.31103.1.5 | fedfsNsdbName | deprecated | 2252 | 1.3.6.1.4.1.31103.1.6 | fedfsNsdbPort | deprecated | 2253 | 1.3.6.1.4.1.31103.1.7 | fedfsNcePrefix | deprecated | 2254 | 1.3.6.1.4.1.31103.1.8 | fedfsFslUuid | RFC-TBD1 | 2255 | 1.3.6.1.4.1.31103.1.9 | fedfsFslHost | deprecated | 2256 | 1.3.6.1.4.1.31103.1.10 | fedfsFslPort | deprecated | 2257 | 1.3.6.1.4.1.31103.1.11 | fedfsFslTTL | deprecated | 2258 | 1.3.6.1.4.1.31103.1.12 | fedfsAnnotation | RFC-TBD1 | 2259 | 1.3.6.1.4.1.31103.1.13 | fedfsDescr | RFC-TBD1 | 2260 | 1.3.6.1.4.1.31103.1.14 | fedfsNceDN | RFC-TBD1 | 2261 | 1.3.6.1.4.1.31103.1.15 | fedfsFsnTTL | RFC-TBD1 | 2262 | 1.3.6.1.4.1.31103.1.100 | fedfsNfsPath | deprecated | 2263 | 1.3.6.1.4.1.31103.1.101 | fedfsNfsMajorVer | deprecated | 2264 | 1.3.6.1.4.1.31103.1.102 | fedfsNfsMinorVer | deprecated | 2265 | 1.3.6.1.4.1.31103.1.103 | fedfsNfsCurrency | RFC-TBD1 | 2266 | 1.3.6.1.4.1.31103.1.104 | fedfsNfsGenFlagWritable | RFC-TBD1 | 2267 | 1.3.6.1.4.1.31103.1.105 | fedfsNfsGenFlagGoing | RFC-TBD1 | 2268 | 1.3.6.1.4.1.31103.1.106 | fedfsNfsGenFlagSplit | RFC-TBD1 | 2269 | 1.3.6.1.4.1.31103.1.107 | fedfsNfsTransFlagRdma | RFC-TBD1 | 2270 | 1.3.6.1.4.1.31103.1.108 | fedfsNfsClassSimul | RFC-TBD1 | 2271 | 1.3.6.1.4.1.31103.1.109 | fedfsNfsClassHandle | RFC-TBD1 | 2272 | 1.3.6.1.4.1.31103.1.110 | fedfsNfsClassFileid | RFC-TBD1 | 2273 | 1.3.6.1.4.1.31103.1.111 | fedfsNfsClassWritever | RFC-TBD1 | 2274 | 1.3.6.1.4.1.31103.1.112 | fedfsNfsClassChange | RFC-TBD1 | 2275 | 1.3.6.1.4.1.31103.1.113 | fedfsNfsClassReaddir | RFC-TBD1 | 2276 | 1.3.6.1.4.1.31103.1.114 | fedfsNfsReadRank | RFC-TBD1 | 2277 | 1.3.6.1.4.1.31103.1.115 | fedfsNfsReadOrder | RFC-TBD1 | 2278 | 1.3.6.1.4.1.31103.1.116 | fedfsNfsWriteRank | RFC-TBD1 | 2279 | 1.3.6.1.4.1.31103.1.117 | fedfsNfsWriteOrder | RFC-TBD1 | 2280 | 1.3.6.1.4.1.31103.1.118 | fedfsNfsVarSub | RFC-TBD1 | 2281 | 1.3.6.1.4.1.31103.1.119 | fedfsNfsValidFor | RFC-TBD1 | 2282 | 1.3.6.1.4.1.31103.1.120 | fedfsNfsURI | RFC-TBD1 | 2283 | 1.3.6.1.4.1.31103.1.1001 | fedfsNsdbContainerInfo | RFC-TBD1 | 2284 | 1.3.6.1.4.1.31103.1.1002 | fedfsFsn | RFC-TBD1 | 2285 | 1.3.6.1.4.1.31103.1.1003 | fedfsFsl | RFC-TBD1 | 2286 | 1.3.6.1.4.1.31103.1.1004 | fedfsNfsFsl | RFC-TBD1 | 2287 +--------------------------+-------------------------+------------+ 2289 Table 1 2291 7.3. LDAP Descriptor Registration 2293 In accordance with Section 3.4 and Section 4 of [RFC4520], the object 2294 identifier descriptors defined in this document (listed below) will 2295 be registered via the Expert Review process. 2297 Subject: Request for LDAP Descriptor Registration 2298 Person & email address to contact for further information: See 2299 "Author/Change Controller" 2300 Specification: draft-ietf-nfsv4-federated-fs-protocol 2301 Author/Change Controller: [document authors] 2303 Object Identifier: 1.3.6.1.4.1.31103.1.1 2304 Descriptor (short name): fedfsUuid 2305 Usage: attribute type 2307 Object Identifier: 1.3.6.1.4.1.31103.1.2 2308 Descriptor (short name): fedfsNetAddr 2309 Usage: attribute type, deprecated 2311 Object Identifier: 1.3.6.1.4.1.31103.1.3 2312 Descriptor (short name): fedfsNetPort 2313 Usage: attribute type, deprecated 2315 Object Identifier: 1.3.6.1.4.1.31103.1.4 2316 Descriptor (short name): fedfsFsnUuid 2317 Usage: attribute type 2319 Object Identifier: 1.3.6.1.4.1.31103.1.5 2320 Descriptor (short name): fedfsNsdbName 2321 Usage: attribute type, deprecated 2323 Object Identifier: 1.3.6.1.4.1.31103.1.6 2324 Descriptor (short name): fedfsNsdbPort 2325 Usage: attribute type, deprecated 2327 Object Identifier: 1.3.6.1.4.1.31103.1.7 2328 Descriptor (short name): fedfsNcePrefix 2329 Usage: attribute type, deprecated 2331 Object Identifier: 1.3.6.1.4.1.31103.1.8 2332 Descriptor (short name): fedfsFslUuid 2333 Usage: attribute type 2334 Object Identifier: 1.3.6.1.4.1.31103.1.9 2335 Descriptor (short name): fedfsFslHost 2336 Usage: attribute type, deprecated 2338 Object Identifier: 1.3.6.1.4.1.31103.1.10 2339 Descriptor (short name): fedfsFslPort 2340 Usage: attribute type, deprecated 2342 Object Identifier: 1.3.6.1.4.1.31103.1.11 2343 Descriptor (short name): fedfsFslTTL 2344 Usage: attribute type, deprecated 2346 Object Identifier: 1.3.6.1.4.1.31103.1.12 2347 Descriptor (short name): fedfsAnnotation 2348 Usage: attribute type 2350 Object Identifier: 1.3.6.1.4.1.31103.1.13 2351 Descriptor (short name): fedfsDescr 2352 Usage: attribute type 2354 Object Identifier: 1.3.6.1.4.1.31103.1.14 2355 Descriptor (short name): fedfsNceDN 2356 Usage: attribute type 2358 Object Identifier: 1.3.6.1.4.1.31103.1.15 2359 Descriptor (short name): fedfsFsnTTL 2360 Usage: attribute type 2362 Object Identifier: 1.3.6.1.4.1.31103.1.100 2363 Descriptor (short name): fedfsNfsPath 2364 Usage: attribute type, deprecated 2366 Object Identifier: 1.3.6.1.4.1.31103.1.101 2367 Descriptor (short name): fedfsNfsMajorVer 2368 Usage: attribute type, deprecated 2370 Object Identifier: 1.3.6.1.4.1.31103.1.102 2371 Descriptor (short name): fedfsNfsMinorVer 2372 Usage: attribute type, deprecated 2374 Object Identifier: 1.3.6.1.4.1.31103.1.103 2375 Descriptor (short name): fedfsNfsCurrency 2376 Usage: attribute type 2377 Object Identifier: 1.3.6.1.4.1.31103.1.104 2378 Descriptor (short name): fedfsNfsGenFlagWritable 2379 Usage: attribute type 2381 Object Identifier: 1.3.6.1.4.1.31103.1.105 2382 Descriptor (short name): fedfsNfsGenFlagGoing 2383 Usage: attribute type 2385 Object Identifier: 1.3.6.1.4.1.31103.1.106 2386 Descriptor (short name): fedfsNfsGenFlagSplit 2387 Usage: attribute type 2389 Object Identifier: 1.3.6.1.4.1.31103.1.107 2390 Descriptor (short name): fedfsNfsTransFlagRdma 2391 Usage: attribute type 2393 Object Identifier: 1.3.6.1.4.1.31103.1.108 2394 Descriptor (short name): fedfsNfsClassSimul 2395 Usage: attribute type 2397 Object Identifier: 1.3.6.1.4.1.31103.1.109 2398 Descriptor (short name): fedfsNfsClassHandle 2399 Usage: attribute type 2401 Object Identifier: 1.3.6.1.4.1.31103.1.110 2402 Descriptor (short name): fedfsNfsClassFileid 2403 Usage: attribute type 2405 Object Identifier: 1.3.6.1.4.1.31103.1.111 2406 Descriptor (short name): fedfsNfsClassWritever 2407 Usage: attribute type 2409 Object Identifier: 1.3.6.1.4.1.31103.1.112 2410 Descriptor (short name): fedfsNfsClassChange 2411 Usage: attribute type 2413 Object Identifier: 1.3.6.1.4.1.31103.1.113 2414 Descriptor (short name): fedfsNfsClassReaddir 2415 Usage: attribute type 2417 Object Identifier: 1.3.6.1.4.1.31103.1.114 2418 Descriptor (short name): fedfsNfsReadRank 2419 Usage: attribute type 2420 Object Identifier: 1.3.6.1.4.1.31103.1.115 2421 Descriptor (short name): fedfsNfsReadOrder 2422 Usage: attribute type 2424 Object Identifier: 1.3.6.1.4.1.31103.1.116 2425 Descriptor (short name): fedfsNfsWriteRank 2426 Usage: attribute type 2428 Object Identifier: 1.3.6.1.4.1.31103.1.117 2429 Descriptor (short name): fedfsNfsWriteOrder 2430 Usage: attribute type 2432 Object Identifier: 1.3.6.1.4.1.31103.1.118 2433 Descriptor (short name): fedfsNfsVarSub 2434 Usage: attribute type 2436 Object Identifier: 1.3.6.1.4.1.31103.1.119 2437 Descriptor (short name): fedfsNfsValidFor 2438 Usage: attribute type 2440 Object Identifier: 1.3.6.1.4.1.31103.1.120 2441 Descriptor (short name): fedfsNfsURI 2442 Usage: attribute type 2444 Object Identifier: 1.3.6.1.4.1.31103.1.1001 2445 Descriptor (short name): fedfsNsdbContainerInfo 2446 Usage: object class 2448 Object Identifier: 1.3.6.1.4.1.31103.1.1002 2449 Descriptor (short name): fedfsFsn 2450 Usage: object class 2452 Object Identifier: 1.3.6.1.4.1.31103.1.1003 2453 Descriptor (short name): fedfsFsl 2454 Usage: object class 2456 Object Identifier: 1.3.6.1.4.1.31103.1.1004 2457 Descriptor (short name): fedfsNfsFsl 2458 Usage: object class 2460 8. Glossary 2462 Administrator: An user with the necessary authority to initiate 2463 administrative tasks on one or more servers. 2465 Admin Entity: A server or agent that administers a collection of 2466 fileservers and persistently stores the namespace information. 2468 Client: Any client that accesses the fileserver data using a 2469 supported filesystem access protocol. 2471 Federation: A set of server collections and singleton servers that 2472 use a common set of interfaces and protocols in order to provide 2473 to their clients a federated namespace accessible through a 2474 filesystem access protocol. 2476 Fileserver: A server exporting a filesystem via a network filesystem 2477 access protocol. 2479 Fileset: The abstraction of a set of files and the directory tree 2480 that contains them. A fileset is the fundamental unit of data 2481 management in the federation. 2483 Note that all files within a fileset are descendants of one 2484 directory, and that filesets do not span filesystems. 2486 Filesystem: A self-contained unit of export for a fileserver, and 2487 the mechanism used to implement filesets. The fileset does not 2488 need to be rooted at the root of the filesystem, nor at the export 2489 point for the filesystem. 2491 A single filesystem MAY implement more than one fileset, if the 2492 client protocol and the fileserver permit this. 2494 Filesystem Access Protocol: A network filesystem access protocol 2495 such as NFSv3 [RFC1813], NFSv4 [3530bis], or CIFS (Common Internet 2496 File System) [MS-SMB] [MS-SMB2] [MS-CIFS]. 2498 FSL (Fileset Location): The location of the implementation of a 2499 fileset at a particular moment in time. An FSL MUST be something 2500 that can be translated into a protocol-specific description of a 2501 resource that a client can access directly, such as an fs_location 2502 (for NFSv4), or share name (for CIFS). Note that not all FSLs 2503 need to be explicitly exported as long as they are contained 2504 within an exported path on the fileserver. 2506 FSN (Fileset Name): A platform-independent and globally unique name 2507 for a fileset. Two FSLs that implement replicas of the same 2508 fileset MUST have the same FSN, and if a fileset is migrated from 2509 one location to another, the FSN of that fileset MUST remain the 2510 same. 2512 Junction: A filesystem object used to link a directory name in the 2513 current fileset with an object within another fileset. The 2514 server-side "link" from a leaf node in one fileset to the root of 2515 another fileset. 2517 Namespace: A filename/directory tree that a sufficiently authorized 2518 client can observe. 2520 NSDB (Namespace Database) Service: A service that maps FSNs to FSLs. 2521 The NSDB may also be used to store other information, such as 2522 annotations for these mappings and their components. 2524 NSDB Node: The name or location of a server that implements part of 2525 the NSDB service and is responsible for keeping track of the FSLs 2526 (and related info) that implement a given partition of the FSNs. 2528 Referral: A server response to a client access that directs the 2529 client to evaluate the current object as a reference to an object 2530 at a different location (specified by an FSL) in another fileset, 2531 and possibly hosted on another fileserver. The client re-attempts 2532 the access to the object at the new location. 2534 Replica: A replica is a redundant implementation of a fileset. Each 2535 replica shares the same FSN, but has a different FSL. 2537 Replicas may be used to increase availability or performance. 2538 Updates to replicas of the same fileset MUST appear to occur in 2539 the same order, and therefore each replica is self-consistent at 2540 any moment. 2542 We do not assume that updates to each replica occur 2543 simultaneously. If a replica is offline or unreachable, the other 2544 replicas may be updated. 2546 Server Collection: A set of fileservers administered as a unit. A 2547 server collection may be administered with vendor-specific 2548 software. 2550 The namespace provided by a server collection could be part of the 2551 federated namespace. 2553 Singleton Server: A server collection containing only one server; a 2554 stand-alone fileserver. 2556 9. References 2557 9.1. Normative References 2559 [3530bis] Haynes, T. and D. Noveck, "NFS Version 4 Protocol", 2560 draft-ietf-nfsv4-rfc3530bis (Work In Progress), 2010. 2562 [RFC2079] Smith, M., "Definition of an X.500 Attribute Type and an 2563 Object Class to Hold Uniform Resource Identifiers (URIs)", 2564 RFC 2079, January 1997. 2566 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2567 Requirement Levels", BCP 14, RFC 2119, March 1997. 2569 [RFC2203] Eisler, M., Chiu, A., and L. Ling, "RPCSEC_GSS Protocol 2570 Specification", RFC 2203, September 1997. 2572 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2573 Schoenwaelder, Ed., "Structure of Management Information 2574 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 2576 [RFC2743] Linn, J., "Generic Security Service Application Program 2577 Interface Version 2, Update 1", RFC 2743, January 2000. 2579 [RFC2849] Good, G., "The LDAP Data Interchange Format (LDIF) - 2580 Technical Specification", RFC 2849, June 2000. 2582 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2583 Resource Identifier (URI): Generic Syntax", STD 66, 2584 RFC 3986, January 2005. 2586 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2587 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2588 July 2005. 2590 [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol 2591 (LDAP): Technical Specification Road Map", RFC 4510, 2592 June 2006. 2594 [RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol 2595 (LDAP): The Protocol", RFC 4511, June 2006. 2597 [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol 2598 (LDAP): Directory Information Models", RFC 4512, 2599 June 2006. 2601 [RFC4513] Harrison, R., "Lightweight Directory Access Protocol 2602 (LDAP): Authentication Methods and Security Mechanisms", 2603 RFC 4513, June 2006. 2605 [RFC4516] Smith, M. and T. Howes, "Lightweight Directory Access 2606 Protocol (LDAP): Uniform Resource Locator", RFC 4516, 2607 June 2006. 2609 [RFC4517] Legg, S., "Lightweight Directory Access Protocol (LDAP): 2610 Syntaxes and Matching Rules", RFC 4517, June 2006. 2612 [RFC4519] Sciberras, A., "Lightweight Directory Access Protocol 2613 (LDAP): Schema for User Applications", RFC 4519, 2614 June 2006. 2616 [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) 2617 Considerations for the Lightweight Directory Access 2618 Protocol (LDAP)", BCP 64, RFC 4520, June 2006. 2620 [RFC4530] Zeilenga, K., "Lightweight Directory Access Protocol 2621 (LDAP) entryUUID Operational Attribute", RFC 4530, 2622 June 2006. 2624 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2625 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2626 May 2008. 2628 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2629 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2631 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2632 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2634 [RFC5661] Shepler, S., Eisler, M., and D. Noveck, "Network File 2635 System (NFS) Version 4 Minor Version 1 Protocol", 2636 RFC 5661, January 2010. 2638 9.2. Informative References 2640 [AFS] Howard, J., "An Overview of the Andrew File System", 2641 Proceeding of the USENIX Winter Technical Conference , 2642 1988. 2644 [FEDFS-ADMIN] 2645 Lentini, J., Everhart, C., Ellard, D., Tewari, R., and M. 2646 Naik, "Administration Protocol for Federated Filesystems", 2647 draft-ietf-nfsv4-federated-fs-admin (Work In Progress), 2648 2010. 2650 [MS-CIFS] Microsoft Corporation, "Common Internet File System (CIFS) 2651 Protocol Specification", MS-CIFS 2.0, November 2009. 2653 [MS-SMB] Microsoft Corporation, "Server Message Block (SMB) 2654 Protocol Specification", MS-SMB 17.0, November 2009. 2656 [MS-SMB2] Microsoft Corporation, "Server Message Block (SMB) Version 2657 2 Protocol Specification", MS-SMB2 19.0, November 2009. 2659 [RFC1813] Callaghan, B., Pawlowski, B., and P. Staubach, "NFS 2660 Version 3 Protocol Specification", RFC 1813, June 1995. 2662 [RFC2224] Callaghan, B., "NFS URL Scheme", RFC 2224, October 1997. 2664 [RFC3254] Alvestrand, H., "Definitions for talking about 2665 directories", RFC 3254, April 2002. 2667 [RFC5662] Shepler, S., Eisler, M., and D. Noveck, "Network File 2668 System (NFS) Version 4 Minor Version 1 External Data 2669 Representation Standard (XDR) Description", RFC 5662, 2670 January 2010. 2672 [RFC5716] Lentini, J., Everhart, C., Ellard, D., Tewari, R., and M. 2673 Naik, "Requirements for Federated File Systems", RFC 5716, 2674 January 2010. 2676 [RFC6641] Everhart, C., Adamson, W., and J. Zhang, "Using DNS SRV to 2677 Specify a Global File Namespace with NFS Version 4", 2678 RFC 6641, June 2012. 2680 Appendix A. Acknowledgments 2682 We would like to thank Andy Adamson of NetApp, Paul Lemahieu of EMC, 2683 Robert Thurlow of Oracle, and Mario Wurzl of EMC for helping to 2684 author this document. 2686 We would like to thank Craig Everhart and Manoj Naik, who were co- 2687 authors of an earlier version of this document. 2689 We would also like to thank George Amvrosiadis, Chuck Lever, Trond 2690 Myklebust, Howard Chu, and Nicolas Williams for their comments. 2692 Finally, we would also like to thank Andy Adamson, Rob Thurlow, Tom 2693 Haynes, and Chuck Lever for the editing effort to get this document 2694 out the door. 2696 The extract.sh shell script and formatting conventions were first 2697 described by the authors of the NFSv4.1 XDR specification [RFC5662]. 2699 Authors' Addresses 2701 James Lentini 2702 NetApp 2703 1601 Trapelo Rd, Suite 16 2704 Waltham, MA 02451 2705 US 2707 Phone: +1 781-768-5359 2708 Email: jlentini@netapp.com 2710 Daniel Ellard 2711 Raytheon BBN Technologies 2712 10 Moulton Street 2713 Cambridge, MA 02138 2714 US 2716 Phone: +1 617-873-8004 2717 Email: dellard@bbn.com 2719 Renu Tewari 2720 IBM Almaden 2721 650 Harry Rd 2722 San Jose, CA 95120 2723 US 2725 Email: tewarir@us.ibm.com 2727 Charles Lever (editor) 2728 Oracle Corporation 2729 1015 Granger Avenue 2730 Ann Arbor, MI 48104 2731 US 2733 Phone: +1 248-614-5091 2734 Email: chuck.lever@oracle.com