idnits 2.17.1 draft-ietf-nfsv4-federated-fs-protocol-15.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 (December 12, 2012) is 4152 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 1549 -- Looks like a reference, but probably isn't: '4294967295' on line 1068 -- Looks like a reference, but probably isn't: '255' on line 1549 ** 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 (==), 6 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: June 15, 2013 Raytheon BBN Technologies 6 R. Tewari 7 IBM Almaden 8 C. Lever, Ed. 9 Oracle Corporation 10 December 12, 2012 12 NSDB Protocol for Federated Filesystems 13 draft-ietf-nfsv4-federated-fs-protocol-15 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 June 15, 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.9.1. NSDB Client . . . . . . . . . . . . . . . . . . . . . 14 92 2.10. Junctions and Referrals . . . . . . . . . . . . . . . . . 14 93 2.11. Unified Namespace and the Root Fileset . . . . . . . . . . 15 94 2.12. UUID Considerations . . . . . . . . . . . . . . . . . . . 15 95 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 96 3.1. Creating a Fileset and its FSL(s) . . . . . . . . . . . . 16 97 3.1.1. Creating a Fileset and an FSN . . . . . . . . . . . . 17 98 3.1.2. Adding a Replica of a Fileset . . . . . . . . . . . . 17 99 3.2. Junction Resolution . . . . . . . . . . . . . . . . . . . 17 100 3.3. Example Use Cases for Fileset Annotations . . . . . . . . 18 101 4. NSDB Configuration and Schema . . . . . . . . . . . . . . . . 19 102 4.1. LDAP Configuration . . . . . . . . . . . . . . . . . . . . 19 103 4.2. LDAP Schema . . . . . . . . . . . . . . . . . . . . . . . 21 104 4.2.1. LDAP Attributes . . . . . . . . . . . . . . . . . . . 23 105 4.2.2. LDAP Object Classes . . . . . . . . . . . . . . . . . 37 106 5. NSDB Operations . . . . . . . . . . . . . . . . . . . . . . . 40 107 5.1. NSDB Operations for Administrators . . . . . . . . . . . . 41 108 5.1.1. Create an FSN . . . . . . . . . . . . . . . . . . . . 41 109 5.1.2. Delete an FSN . . . . . . . . . . . . . . . . . . . . 42 110 5.1.3. Create an FSL . . . . . . . . . . . . . . . . . . . . 43 111 5.1.4. Delete an FSL . . . . . . . . . . . . . . . . . . . . 46 112 5.1.5. Update an FSL . . . . . . . . . . . . . . . . . . . . 47 113 5.2. NSDB Operations for Fileservers . . . . . . . . . . . . . 48 114 5.2.1. NSDB Container Entry (NCE) Enumeration . . . . . . . . 48 115 5.2.2. Lookup FSLs for an FSN . . . . . . . . . . . . . . . . 48 116 5.3. NSDB Operations and LDAP Referrals . . . . . . . . . . . . 49 117 6. Security Considerations . . . . . . . . . . . . . . . . . . . 50 118 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 51 119 7.1. Registry for the fedfsAnnotation Key Namespace . . . . . . 51 120 7.2. Registry for FedFS Object Identifiers . . . . . . . . . . 51 121 7.3. LDAP Descriptor Registration . . . . . . . . . . . . . . . 54 123 8. Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 124 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 60 125 9.1. Normative References . . . . . . . . . . . . . . . . . . . 60 126 9.2. Informative References . . . . . . . . . . . . . . . . . . 61 127 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 62 128 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 63 130 1. Introduction 132 A federated filesystem enables file access and namespace traversal in 133 a uniform, secure and consistent manner across multiple independent 134 fileservers within an enterprise or across multiple enterprises. 136 This document specifies a set of protocols that allow fileservers, 137 possibly from different vendors and with different administrators, to 138 cooperatively form a federation containing one or more federated 139 filesystems. Each federated filesystem's namespace is composed of 140 the filesystems physically hosted on and exported by the federation's 141 fileservers. A federation comprises a common namespace across all 142 its fileservers. A federation can project multiple namespaces and 143 enable clients to traverse each one. A federation can contain an 144 arbitrary number of namespace repositories, each belonging to a 145 different administrative entity, and each rendering a part of the 146 namespace. A federation might also have an arbitrary number of 147 administrative entities responsible for administering disjoint 148 subsets of the fileservers. 150 Traditionally, building a namespace that spans multiple fileservers 151 has been difficult for two reasons. First, the fileservers that 152 export pieces of the namespace are often not in the same 153 administrative domain. Second, there is no standard mechanism for 154 the fileservers to cooperatively present the namespace. Fileservers 155 may provide proprietary management tools and in some cases an 156 administrator may be able to use the proprietary tools to build a 157 shared namespace out of the exported filesystems. However, relying 158 on vendor-specific proprietary tools does not work in larger 159 enterprises or when collaborating across enterprises because the 160 fileservers are likely to be from multiple vendors or use different 161 software versions, each with their own namespace protocols, with no 162 common mechanism to manage the namespace or exchange namespace 163 information. 165 The federated filesystem protocols in this document define how to 166 construct a namespace accessible by an NFSv4.0 [3530bis], NFSv4.1 167 [RFC5661] or newer client and have been designed to accommodate other 168 file access protocols in the future. 170 The requirements for federated filesystems are described in 171 [RFC5716]. A protocol for administering a fileserver's namespace is 172 described in [FEDFS-ADMIN]. The mechanism for discovering the root 173 of a federated namespace is described in [RFC6641]. 175 In the rest of the document, the term fileserver denotes a fileserver 176 that is part of a federation. 178 2. Overview of Features and Concepts 180 2.1. File-access Protocol 182 A file-access protocol is a network protocol for accessing data. The 183 NFSv4.0 protocol [3530bis] is an example of a file-access protocol. 185 2.2. File-access Client 187 File-access clients are standard off-the-shelf network attached 188 storage (NAS) clients that communicate with fileservers using a 189 standard file-access protocol. 191 2.3. Fileserver 193 Fileservers are servers that store physical fileset data, or refer 194 file-access clients to other fileservers. A fileserver provides 195 access to its shared filesystem data via a file-access protocol. A 196 fileserver may be implemented in a number of different ways, 197 including a single system, a cluster of systems, or some other 198 configuration. 200 2.4. Referral 202 A referral is a mechanism by which a fileserver redirects a file- 203 access client to a different fileserver or export. The exact 204 information contained in a referral varies from one file-access 205 protocol to another. The NFSv4.0 protocol, for example, defines the 206 fs_locations attribute for returning referral information to NFSv4.0 207 clients. The NFSv4.1 protocol introduces the fs_locations_info 208 attribute that can return richer referral information to its clients. 209 NFSv4.1 fileservers may use either attribute during a referral. Both 210 attributes are defined in [RFC5661]. 212 2.5. Namespace 214 The goal of a unified namespace is to make all managed data available 215 to any file-access client via the same path in a common filesystem 216 namespace. This should be achieved with minimal or zero 217 configuration on file-access clients. In particular, updates to the 218 common namespace should not require configuration changes to any 219 file-access client. 221 Filesets, which are the unit of data management, are a set of files 222 and directories. From the perspective of file-access clients, the 223 common namespace is constructed by mounting filesets that are 224 physically located on different fileservers. The namespace, which is 225 defined in terms of fileset names and locations, is stored in a set 226 of namespace repositories, each managed by an administrative entity. 228 The namespace schema defines the model used for populating, 229 modifying, and querying the namespace repositories. It is not 230 required by the federation that the namespace be common across all 231 fileservers. It should be possible to have several independently 232 rooted namespaces. 234 2.6. Fileset 236 A fileset is loosely defined as a set of files and the directory tree 237 that contains them. The fileset abstraction is the basic unit of 238 data management. Depending on the configuration, a fileset may be 239 anything from an individual directory of an exported filesystem to an 240 entire exported filesystem on a fileserver. 242 2.7. Fileset Name (FSN) 244 A fileset is uniquely represented by its fileset name (FSN). An FSN 245 is considered unique across a federation. After an FSN is created, 246 it is associated with one or more fileset locations (FSLs) on one or 247 more fileservers. 249 An FSN consists of: 251 NsdbName: the network location of the Namespace Database (NSDB) 252 node that contains authoritative information for this FSN. 254 FsnUuid: a UUID (universally unique identifier), conforming to 255 [RFC4122], that is used to uniquely identify an FSN. 257 FsnTTL: the time-to-live of the FSN's FSL information, in 258 seconds. Fileservers MUST NOT use cached FSL records after the 259 parent FSN's FsnTTL has expired. An FsnTTL value of zero 260 indicates that fileservers MUST NOT cache the results of 261 resolving this FSN. 263 The NsdbName is not physically stored as an attribute of the record. 264 The NsdbName is obvious to any client that accesses an NSDB, and is 265 indeed authenticated in cases where TLS security is in effect. 267 The FsnUuid and NsdbName values never change during an FSN's 268 lifetime. However, an FSN's FSL information can change over time, 269 and is typically cached on fileservers for performance. More detail 270 on FSL caching is provided in Section 2.8.3. 272 An FSN record may also contain: 274 Annotations: name/value pairs that can be interpreted by a 275 fileserver. The semantics of this field are not defined by 276 this document. These tuples are intended to be used by higher- 277 level protocols. 279 Descriptions: text descriptions. The semantics of this field are 280 not defined by this document. 282 2.8. Fileset Location (FSL) 284 An FSL describes one physical location where a complete copy of the 285 fileset's data resides. An FSL contains generic and type specific 286 information which together describe how to access the fileset data at 287 this location. An FSL's attributes can be used by a fileserver to 288 decide which locations it will return to a file-access client. 290 An FSL consists of: 292 FslUuid: a UUID, conforming to [RFC4122], that is used to 293 uniquely identify an FSL. 295 FsnUuid: the UUID of the FSL's FSN. 297 NsdbName: the network location of the NSDB node that contains 298 authoritative information for this FSL. 300 The NsdbName is not stored as an attribute of an FSL record for the 301 same reason it is not stored in FSN records. 303 An FSL record may also contain: 305 Annotations: name/value pairs that can be interpreted by a 306 fileserver. The semantics of this field are not defined by 307 this document. These tuples are intended to be used by higher- 308 level protocols. 310 Descriptions: text descriptions. The semantics of this field are 311 not defined by this document. 313 In addition to the attributes defined above, an FSL record contains 314 attributes that allow a fileserver to construct referrals. For each 315 file-access protocol, a corresponding FSL record subtype is defined. 317 This document defines an FSL subtype for NFS. An NFS FSL contains 318 information suitable for use in one of the NFSv4 referral attributes 319 (e.g., fs_locations or fs_locations_info, described in [RFC5661]). 320 Section 4.2.2.4 describes the contents of an NFS FSL record. 322 A fileset also may be accessible by file-access protocols other than 323 NFS. The contents and format of such FSL subtypes are not defined in 324 this document. 326 2.8.1. The NFS URI scheme 328 To capture the location of an NFSv4 fileset, we extend the NFS URL 329 scheme specified in [RFC2224]. This extension follows rules for 330 defining Uniform Resource Identifier schemes (see [RFC3986]). In the 331 following text, we refer to this extended NFS URL scheme as an NFS 332 URI. 334 An NFS URI MUST contain both an authority and a path component. It 335 MUST NOT contain a query component or a fragment component. Use of 336 the familiar "nfs" scheme name is retained. 338 2.8.1.1. The NFS URI authority component 340 The rules for encoding the authority component of a generic URI are 341 specified in section 3.2 of [RFC3986]. The authority component of an 342 NFS URI MUST contain the host subcomponent. For globally-scoped NFS 343 URIs, a hostname used in such URIs SHOULD be a fully qualified domain 344 name. See section 3.2.2 of [RFC3986] for rules on encoding non-ASCII 345 characters in hostnames. 347 An NFS URI MAY contain a port subcomponent as described in section 348 3.2.3 of [RFC3986]. If this subcomponent is missing, a port value of 349 2049 is assumed, as specified in [3530bis], Section 3.1. 351 2.8.1.2. The NFS URI path component 353 The rules for encoding the path component of a generic URI are 354 specified in section 3.3 of [RFC3986]. 356 According to sections 5 and 6 of [RFC2224], NFS URLs specify a 357 pathname relative to an NFS fileserver's "public filehandle." 358 However, NFSv4 fileservers do not expose a "public filehandle." 359 Instead, NFSv4 pathnames contained in an NFS URI are evaluated 360 relative to the pseudoroot of the fileserver identified in the URI's 361 authority component. 363 Each component of an NFSv4 pathname is represented as a component4 364 string (see Section 3.2, "Basic Data Types" of [RFC5661]). The 365 component4 elements of an NFSv4 pathname are encoded as path segments 366 in an NFS URI. NFSv4 pathnames MUST be expressed in an NFS URI as an 367 absolute path. An NFS URI path component MUST NOT be empty. The NFS 368 URI path component starts with a slash ("/") character, followed by 369 one or more path segments which each start with a slash ("/") 370 character [RFC3986]. 372 Therefore, a double slash always follows the authority component of 373 an NFS URI. For example, the NFSv4 pathname "/" is represented by 374 two slash ("/") characters following an NFS URI's authority 375 component. 377 The component4 elements of an NFSv4 pathname MUST be prepared using 378 the component4 rules defined in Chapter 12 "Internationalization" of 379 [3530bis] prior to encoding the path component of an NFS URI. As 380 specified in [RFC3986], any non-ASCII characters and any URI-reserved 381 characters, such as the slash ("/") character, contained in a 382 component4 element MUST be represented by URI percent encoding. 384 2.8.1.3. Encoding an NFS location in an FSL 386 The path component of an NFS URI encodes the "rootpath" field of the 387 NFSv4 fs_location4 data type or the "fli_rootpath" of the NFSv4 388 fs_locations_item4 data type (see [RFC5661]). 390 In its "server" field, the NFSv4 fs_location4 data type contains a 391 list of universal addresses and DNS labels. Each may optionally 392 include a port number. The exact encoding requirements for this 393 information is found in Section 12.6 of [3530bis]. The NFSv4 394 fs_locations_item4 data type encodes the same data in its 395 "fli_entries" field (see [RFC5661]). This information is encoded in 396 the authority component of an NFS URI. 398 The "server" and "fli_entries" fields can encode multiple server 399 hostnames that share the same pathname. An NFS URI, and hence an FSL 400 record, represents only a single hostname and pathname pair. An NFS 401 fileserver MUST NOT combine a set of FSL records into a single 402 fs_location4 or fs_locations_item4 unless each FSL record in the set 403 contains the same rootpath value and extended filesystem information. 405 2.8.2. Mutual Consistency across Fileset Locations 407 All of the FSLs that have the same FSN (and thereby reference the 408 same fileset) are equivalent from the point of view of access by a 409 file-access client. Different fileset locations for an FSN represent 410 the same data, though potentially at different points in time. 411 Fileset locations are equivalent but not identical. Locations may 412 either be read-only or read-write. Typically, multiple read-write 413 locations are backed by a clustered filesystem while read-only 414 locations are replicas created by a federation-initiated or external 415 replication operation. Read-only locations may represent consistent 416 point-in-time copies of a read-write location. The federation 417 protocols, however, cannot prevent subsequent changes to a read-only 418 location nor guarantee point-in-time consistency of a read-only 419 location if the read-write location is changing. 421 Regardless of the type, one file-access client may be referred to a 422 location described by one FSL while another client chooses to use a 423 location described by another FSL. Since updates to each fileset 424 location are not controlled by the federation protocol, it is the 425 responsibility of administrators to guarantee the functional 426 equivalence of the data. 428 The federation protocols do not guarantee that different fileset 429 locations are mutually consistent in terms of the currency of their 430 data. However, they provide a means to publish currency information 431 so that all fileservers in a federation can convey the same 432 information to file-access clients during referrals. Clients use 433 this information to ensure they do not revert to an out-of-date 434 version of a fileset's data when switching between fileset locations. 435 NFSv4.1 provides guidance on how replication can be handled in such a 436 manner. In particular see Section 11.7 of [RFC5661]. 438 2.8.3. Caching of Fileset Locations 440 To resolve an FSN to a set of FSL records, a fileserver queries the 441 NSDB node named in the FSN for FSL records associated with this FSN. 442 The parent FSN's FsnTTL attribute (see Section 2.7) specifies the 443 period of time during which a fileserver may cache these FSL records. 445 The combination of FSL caching and FSL migration presents a 446 challenge. For example, suppose there are three fileservers named A, 447 B, and C. Suppose further that fileserver A contains a junction J to 448 fileset X stored on fileserver B (see Section 2.10 for a description 449 of junctions). 451 Now suppose that fileset X is migrated from fileserver B to 452 fileserver C, and the corresponding FSL information for fileset X in 453 the authoritative NSDB is updated. 455 If fileserver A has cached FSLs for fileset X, a file-access client 456 traversing junction J on fileserver A will be referred to fileserver 457 B, even though fileset X has migrated to fileserver C. If fileserver 458 A had not cached the FSL records, it would have queried the NSDB and 459 obtained the correct location of fileset X. 461 Typically, the process of fileset migration leaves a redirection on 462 the source fileserver in place of a migrated fileset (without such a 463 redirection, file-access clients would find an empty space where the 464 migrated fileset was, which defeats the purpose of a managed 465 migration). 467 This redirection might be a new junction that targets the same FSN as 468 other junctions referring to the migrated fileset, or it might be 469 some other kind of directive, depending on the fileserver 470 implementation, that simply refers file-access clients to the new 471 location of the migrated fileset. 473 Back to our example. Suppose, as part of the migration process, a 474 junction replaces fileset X on fileserver B. Later, either: 476 o New file-access clients are referred to fileserver B by stale FSL 477 information cached on fileserver A, or 479 o File-access clients continue to access fileserver B because they 480 cache stale location data for fileset X. 482 In either case, thanks to the redirection, file-access clients are 483 informed by fileserver B that fileset X has moved to fileserver C. 485 Such redirecting junctions (here, on fileserver B) would not be 486 required to be in place forever. They need to stay in place at least 487 until FSL entries cached on fileservers and locations cached on file- 488 access clients for the target fileset are invalidated. 490 The FsnTTL field in the FSL's parent FSN (see Section 2.7) specifies 491 an upper bound for the lifetime of cached FSL information, and thus 492 can act as a lower bound for the lifetime of redirecting junctions. 494 For example, suppose the FsnTTL field contains the value 3600 seconds 495 (one hour). In such a case, administrators SHOULD keep the 496 redirection in place for at least one hour after a fileset migration 497 has taken place, because a referring fileserver might cache the FSL 498 data during that time before refreshing it. 500 To get file-access clients to access the destination fileserver more 501 quickly, administrators SHOULD set the FsnTTL field of the migrated 502 fileset to a low number or zero before migration begins. It can be 503 reset to a more reasonable number at a later point. 505 Note that some file-access protocols do not communicate location 506 cache expiry information to file-access clients. In some cases it 507 may be difficult to determine an appropriate lifetime for redirecting 508 junctions because file-access clients may cache location information 509 indefinitely. 511 2.8.4. Generating A Referral from Fileset Locations 513 After resolving an FSN to a set of FSL records, the fileserver 514 generates a referral to redirect a file-access client to one or more 515 of the FSN's FSLs. The fileserver converts the FSL records to a 516 referral format understood by a particular file-access client, such 517 as an NFSv4 fs_locations or fs_locations_info attribute. 519 To give file-access clients as many options as possible, the 520 fileserver SHOULD include the maximum possible number of FSL records 521 in a referral. However, the fileserver MAY omit some of the FSL 522 records from the referral. For example, the fileserver might omit an 523 FSL record because of limitations in the file access protocol's 524 referral format. 526 For a given FSL record, the fileserver MAY convert or reduce the FSL 527 record's contents in a manner appropriate to the referral format. 528 For example, an NFS FSL record contains all the data necessary to 529 construct an fs_locations_info attribute, but an fs_locations_info 530 attribute contains several pieces of information that are not found 531 in the simpler fs_locations attribute. A fileserver constructs 532 entries in an fs_locations attribute using the relevant contents of 533 an NFS FSL record. 535 Whenever the fileserver converts or reduces FSL data, the fileserver 536 SHOULD attempt to maintain the original meaning where possible. For 537 example, an NFS FSL record contains the rank and order information 538 that is included in an fs_locations_info attribute (see NFSv4.1's 539 FSLI4BX_READRANK, FSLI4BX_READORDER, FSLI4BX_WRITERANK, and 540 FSLI4BX_WRITEORDER). While this rank and order information is not 541 explicitly expressible in an fs_locations attribute, the fileserver 542 can arrange the fs_locations attribute's locations list based on the 543 rank and order values. 545 Another example: A single NFS FSL record contains the hostname of one 546 fileserver. A single fs_locations attribute can contain a list of 547 fileserver names. An NFS fileserver MAY combine two or more FSL 548 records into a single entry in an fs_locations or fs_locations_info 549 array only if each FSL record contains the same pathname and extended 550 filesystem information. 552 Refer to the NFSv4.1 protocol specification [RFC5661], sections 11.9 553 and 11.10, for further details. 555 2.9. Namespace Database (NSDB) 557 The NSDB service is a federation-wide service that provides 558 interfaces to define, update, and query FSN information, FSL 559 information, and FSN to FSL mapping information. 561 An individual repository of namespace information is called an NSDB 562 node. The difference between the NSDB service and an NSDB node is 563 analogous to that between the DNS service and a particular DNS 564 server. 566 Each NSDB node is managed by a single administrative entity. A 567 single administrative entity can manage multiple NSDB nodes. 569 Each NSDB node stores the definition of the FSNs for which it is 570 authoritative. It also stores the definitions of the FSLs associated 571 with those FSNs. An NSDB node is authoritative for the filesets that 572 it defines. 574 An NSDB MAY be replicated throughout the federation. If an NSDB is 575 replicated, the NSDB MUST exhibit loose, converging consistency as 576 defined in [RFC3254]. The mechanism by which this is achieved is 577 outside the scope of this document. Many LDAP implementations 578 support replication. These features MAY be used to replicate the 579 NSDB. 581 2.9.1. NSDB Client 583 Each NSDB node supports an LDAP [RFC4510] interface. An NSDB client 584 is software that uses the LDAP protocol to access or update namespace 585 information stored on an NSDB node. Details of these transactions 586 are discussed in Section 4. 588 A domain's administrative entity uses NSDB client software to manage 589 information stored on NSDB nodes. 591 Fileservers act as an NSDB client when contacting a particular NSDB 592 node to resolve an FSN to a set of FSL records. The resulting 593 location information is then transferred to file-access clients via 594 referrals. Therefore file-access clients never have need to access 595 NSDBs directly. 597 2.10. Junctions and Referrals 599 A junction is a point in a particular fileset namespace where a 600 specific target fileset may be attached. If a file-access client 601 traverses the path leading from the root of a federated namespace to 602 the junction referring to a target fileset, it should be able to 603 mount and access the data in that target fileset (assuming 604 appropriate permissions). In other words, a junction can be viewed 605 as a reference from a directory in one fileset to the root of the 606 target fileset. 608 A junction can be implemented as a special marker on a directory, or 609 by some other mechanism in the fileserver's underlying filesystem. 610 What data is used by the fileserver to represent junctions is not 611 defined by this document. The essential property is that given a 612 junction, a fileserver must be able to find the FSN for the target 613 fileset. 615 When a file-access client reaches a junction, the fileserver refers 616 the client to a list of FSLs associated with the FSN targeted by the 617 junction. The client can then mount one of the associated FSLs. 619 The federation protocols do not limit where and how many times a 620 fileset is mounted in the namespace. Filesets can be nested; a 621 fileset can be mounted under another fileset. 623 2.11. Unified Namespace and the Root Fileset 625 The root fileset, when defined, is the top-level fileset of the 626 federation-wide namespace. The root of the unified namespace is the 627 top level directory of this fileset. A set of designated fileservers 628 in the federation can export the root fileset to render the 629 federation-wide unified namespace. When a file-access client mounts 630 the root fileset from any of these designated fileservers it can view 631 a common federation-wide namespace. 633 2.12. UUID Considerations 635 To ensure FSN and FSL records are unique across a domain, FedFS 636 employs UUIDs conforming to [RFC4122] to form the distinguished names 637 of LDAP records containing FedFS data (see Section 4.2.2.2). 639 Because junctions store a tuple containing an FSN UUID and the name 640 and port of an NSDB node, an FSN UUID must be unique only on a single 641 NSDB node. An FSN UUID collision can be detected immediately when an 642 administrator attempts to publish an FSN or FSL by storing it under a 643 specific NSDB Container Entry (NCE) on an authoritative NSDB host. 645 Note that one NSDB node may store multiple NCEs, each under a 646 different namingContext. If an NSDB node must contain more than one 647 NCE, the federation's admin entity SHOULD provide a robust method for 648 preventing FSN UUID collisions between FSNs that reside on the same 649 NSDB node but under different NCEs. 651 Because FSLs are children of FSNs, FSL UUIDs must be unique for just 652 a single FSN. As with FSNs, as soon as an FSL is published, its 653 uniqueness is guaranteed. 655 A fileserver performs the operations described in Section 5.2 as an 656 unauthenticated user. Thus distinguished names of FSN and FSL 657 records, as well as the FSN and FSL records themselves, are required 658 to be readable by anyone who can bind anonymously to an NSDB node. 660 Therefore FSN and FSL UUIDs should be considered public information. 662 Version 1 UUIDs contain a host's MAC address and a time stamp in the 663 clear. This gives provenance to each UUID, but attackers can use 664 such details to guess information about the host where the UUID was 665 generated. Security-sensitive installations should be aware that on 666 externally-facing NSDBs, UUIDs can reveal information about the hosts 667 where they are generated. 669 In addition, version 1 UUIDs depend on the notion that a hardware MAC 670 address is unique across machines. As virtual machines do not depend 671 on unique physical MAC addresses and in any event an administrator 672 can modify the physical MAC address, version 1 UUIDs are no longer 673 considered sufficient. 675 To minimize the probability of UUIDs colliding, a consistent 676 procedure for generating UUIDs should be used throughout a 677 federation. Within a federation, UUIDs SHOULD be generated using the 678 procedure described for version 4 of the UUID variant specified in 679 [RFC4122]. 681 3. Examples 683 In this section we provide examples and discussion of the basic 684 operations facilitated by the federated filesystem protocol: creating 685 a fileset, adding a replica of a fileset, resolving a junction, and 686 creating a junction. 688 3.1. Creating a Fileset and its FSL(s) 690 A fileset is the abstraction of a set of files and the directory tree 691 that contains them. The fileset abstraction is the fundamental unit 692 of data management in the federation. This abstraction is 693 implemented by an actual directory tree whose root location is 694 specified by a fileset location (FSL). 696 In this section, we describe the basic requirements for starting with 697 a directory tree and creating a fileset that can be used in the 698 federation protocols. Note that we do not assume that the process of 699 creating a fileset requires any transformation of the files or the 700 directory hierarchy. The only thing that is required by this process 701 is assigning the fileset a fileset name (FSN) and expressing the 702 location of the implementation of the fileset as an FSL. 704 There are many possible variations to this procedure, depending on 705 how the FSN that binds the FSL is created, and whether other replicas 706 of the fileset exist, are known to the federation, and need to be 707 bound to the same FSN. 709 It is easiest to describe this in terms of how to create the initial 710 implementation of the fileset, and then describe how to add replicas. 712 3.1.1. Creating a Fileset and an FSN 714 1. Choose the NSDB node that will keep track of the FSL(s) and 715 related information for the fileset. 717 2. Create an FSN in the NSDB node. 719 The FSN UUID is chosen by the administrator or generated 720 automatically by administration software. The former case is 721 used if the fileset is being restored, perhaps as part of 722 disaster recovery, and the administrator wishes to specify the 723 FSN UUID in order to permit existing junctions that reference 724 that FSN to work again. 726 At this point, the FSN exists, but its fileset locations are 727 unspecified. 729 3. For the FSN created above, create an FSL in the NSDB node that 730 describes the physical location of the fileset data. 732 3.1.2. Adding a Replica of a Fileset 734 Adding a replica is straightforward: the NSDB node and the FSN are 735 already known. The only remaining step is to add another FSL. 737 Note that the federation protocols provide only the mechanisms to 738 register and unregister replicas of a fileset. Fileserver-to- 739 fileserver replication protocols are not defined. 741 3.2. Junction Resolution 743 A fileset may contain references to other filesets. These references 744 are represented by junctions. If a file-access client requests 745 access to a fileset object that is a junction, the fileserver 746 resolves the junction to discover one or more FSLs that implement the 747 referenced fileset. 749 There are many possible variations to this procedure, depending on 750 how the junctions are represented by the fileserver and how the 751 fileserver performs junction resolution. 753 Step 4 is the only step that interacts directly with the federation 754 protocols. The rest of the steps may use platform-specific 755 interfaces. 757 1. The fileserver determines that the object being accessed is a 758 junction. 760 2. The fileserver does a local lookup to find the FSN of the target 761 fileset. 763 3. Using the FSN, the fileserver finds the NSDB node responsible for 764 the target FSN. 766 4. The fileserver contacts that NSDB node and asks for the set of 767 FSLs that implement the target FSN. The NSDB node responds with 768 a (possibly empty) set of FSLs. 770 5. The fileserver converts one or more of the FSLs to the location 771 type used by the file-access client (e.g., an NFSv4 fs_locations 772 attribute as described in [RFC5661]). 774 6. The fileserver redirects (in whatever manner is appropriate for 775 the client) the client to the location(s). 777 3.3. Example Use Cases for Fileset Annotations 779 Fileset annotations can convey additional attributes of a fileset. 780 For example, fileset annotations can be used to define relationships 781 between filesets that can be used by an auxiliary replication 782 protocol. Consider the scenario where a fileset is created and 783 mounted at some point in the namespace. A snapshot of the read-write 784 FSL of that fileset is taken periodically at different frequencies 785 (say, a daily or weekly snapshot). The different snapshots are 786 mounted at different locations in the namespace. 788 The daily snapshots are considered as different filesets from the 789 weekly ones, but both are related to the source fileset. We can 790 define an annotation labeling the filesets as source and replica. 791 The replication protocol can use this information to copy data from 792 one or more FSLs of the source fileset to all the FSLs of the replica 793 fileset. The replica filesets are read-only while the source fileset 794 is read-write. 796 This follows the traditional Andrew File System (AFS) model of 797 mounting the read-only volume at a path in the namespace different 798 from that of the read-write volume [AFS]. 800 The federation protocol does not control or manage the relationship 801 among filesets. It merely enables annotating the filesets with user- 802 defined relationships. 804 Another potential use for annotations is recording references to an 805 FSN. A single annotation containing the number of references could 806 be defined; or multiple annotations, one per reference, could be used 807 to store detailed information on the location of each reference. 809 As with the replication annotation described above, the maintenance 810 of reference information would not be controlled by the federation 811 protocol. The information would most likely be non-authoritative 812 because the ability to create a junction does not require the 813 authority to update the FSN record. In any event, such annotations 814 could be useful to administrators for determining if an FSN is 815 referenced by a junction. 817 4. NSDB Configuration and Schema 819 This section describes how an NSDB is constructed using an LDAP 820 Version 3 [RFC4510] Directory. Section 4.1 describes the basic 821 properties of the LDAP configuration that MUST be used in order to 822 ensure compatibility between different implementations. Section 4.2 823 defines the new LDAP attribute types, the new object types, and 824 specifies how the distinguished name (DN) of each object instance 825 MUST be constructed. 827 4.1. LDAP Configuration 829 An NSDB is constructed using an LDAP Directory. This LDAP Directory 830 MAY have multiple naming contexts. The LDAP Directory's DSA-specific 831 entry (its rootDSE) has a multi-valued namingContext attribute. Each 832 value of the namingContext attribute is the DN of a naming context's 833 root entry (see [RFC4512]). 835 For each naming context that contains federation entries (e.g., FSNs 836 and FSLs): 838 1. There MUST be an LDAP entry that is superior to all of the naming 839 context's federation entries in the Directory Information Tree 840 (DIT). This entry is termed the NSDB Container Entry (NCE). The 841 NCE's children are FSNs. An FSN's children are FSLs. 843 2. The naming context's root entry MUST include the 844 fedfsNsdbContainerInfo (defined below) as one of its object 845 classes. The fedfsNsdbContainerInfo's fedfsNceDN attribute is 846 used to locate the naming context's NCE. 848 If a naming context does not contain federation entries, it will not 849 contain an NCE and its root entry will not include a 850 fedfsNsdbContainerInfo as one of its object classes. 852 A fedfsNsdbContainerInfo's fedfsNceDN attribute contains the 853 Distinguished Name (DN) of the NSDB Container Entry residing under 854 this naming context. The fedfsNceDN attribute MUST NOT be empty. 856 For example, an LDAP directory might have the following entries: 858 -+ [root DSE] 859 | namingContext: o=fedfs 860 | namingContext: dc=example,dc=com 861 | namingContext: ou=system 862 | 863 | 864 +---- [o=fedfs] 865 | fedfsNceDN: o=fedfs 866 | 867 | 868 +---- [dc=example,dc=com] 869 | fedfsNceDN: ou=fedfs,ou=corp-it,dc=example,dc=com 870 | 871 | 872 +---- [ou=system] 874 In this case, the o=fedfs namingContext has an NSDB Container Entry 875 at o=fedfs, the dc=example,dc=com namingContext has an NSDB Container 876 Entry at ou=fedfs,ou=corp-it,dc=example,dc=com, and the ou=system 877 namingContext has no NSDB Container Entry. 879 The NSDB SHOULD be configured with one or more privileged LDAP users. 880 These users are able to modify the contents of the LDAP database. An 881 administrator that performs the operations described in Section 5.1 882 SHOULD authenticate using the DN of a privileged LDAP user. 884 It MUST be possible for an unprivileged (unauthenticated) user to 885 perform LDAP queries that access the NSDB data. A fileserver 886 performs the operations described in Section 5.2 as an unprivileged 887 user. 889 All implementations SHOULD use the same schema. At minimum, each 890 MUST use a schema that includes all objects named in the following 891 sections, with all associated attributes. If it is necessary for an 892 implementation to extend the schema defined here, consider using one 893 of the following ways to extend the schema: 895 o Define a fedfsAnnotation key and values (see Section 4.2.1.6). 896 Register the new key and values with IANA (see Section 7.1). 898 o Define additional attribute types and object classes, then have 899 entries inherit from a class defined in this document and from the 900 implementation-defined ones. 902 Given the above configuration guidelines, an NSDB SHOULD be 903 constructed using a dedicated LDAP server. If LDAP directories are 904 needed for other purposes, such as to store user account information, 905 use of a separate LDAP server for those is RECOMMENDED. By using an 906 LDAP server dedicated to storing NSDB records, there is no need to 907 disturb the configuration of any other LDAP directories that store 908 information unrelated to an NSDB. 910 4.2. LDAP Schema 912 The schema definitions provided in this document use the LDAP schema 913 syntax defined in [RFC4512]. The definitions are formatted to allow 914 the reader to easily extract them from the document. The reader can 915 use the following shell script to extract the definitions: 917 919 #!/bin/sh 920 grep '^ *///' | sed 's?^ */// ??' | sed 's?^ *///$??' 922 924 If the above script is stored in a file called "extract.sh", and this 925 document is in a file called "spec.txt", then the reader can do: 927 929 sh extract.sh < spec.txt > fedfs.schema 931 933 The effect of the script is to remove leading white space from each 934 line, plus a sentinel sequence of "///". 936 Code components extracted from this document must include the 937 following license: 939 940 /// # 941 /// # Copyright (c) 2010-2012 IETF Trust and the persons identified 942 /// # as authors of the code. All rights reserved. 943 /// # 944 /// # The authors of the code are the authors of 945 /// # [draft-ietf-nfsv4-federated-fs-protocol-xx.txt]: J. Lentini, 946 /// # C. Everhart, D. Ellard, R. Tewari, and M. Naik. 947 /// # 948 /// # Redistribution and use in source and binary forms, with 949 /// # or without modification, are permitted provided that the 950 /// # following conditions are met: 951 /// # 952 /// # - Redistributions of source code must retain the above 953 /// # copyright notice, this list of conditions and the 954 /// # following disclaimer. 955 /// # 956 /// # - Redistributions in binary form must reproduce the above 957 /// # copyright notice, this list of conditions and the 958 /// # following disclaimer in the documentation and/or other 959 /// # materials provided with the distribution. 960 /// # 961 /// # - Neither the name of Internet Society, IETF or IETF 962 /// # Trust, nor the names of specific contributors, may be 963 /// # used to endorse or promote products derived from this 964 /// # software without specific prior written permission. 965 /// # 966 /// # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 967 /// # AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED 968 /// # WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 969 /// # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 970 /// # FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO 971 /// # EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 972 /// # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 973 /// # EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 974 /// # NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 975 /// # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 976 /// # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 977 /// # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 978 /// # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 979 /// # IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 980 /// # ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 981 /// # 983 985 4.2.1. LDAP Attributes 987 The following definitions are used below: 989 o The "name" attribute described in [RFC4519]. 991 o The Integer syntax (1.3.6.1.4.1.1466.115.121.1.27) described in 992 [RFC4517]. 994 o The "integerMatch" rule described in [RFC4517]. 996 o The Octet String syntax (1.3.6.1.4.1.1466.115.121.1.40) described 997 in [RFC4517]. 999 o The "octetStringMatch" rule described in [RFC4517]. 1001 o The Boolean syntax (1.3.6.1.4.1.1466.115.121.1.7) described in 1002 [RFC4517]. 1004 o The "booleanMatch" rule described in [RFC4517]. 1006 o The "distinguishedNameMatch" rule described in [RFC4517]. 1008 o The DN syntax (1.3.6.1.4.1.1466.115.121.1.12) described in 1009 [RFC4517]. 1011 o The "labeledURI" attribute described in [RFC2079]. 1013 o The UUID syntax (1.3.6.1.1.16.1) described in [RFC4530]. 1015 o The UuidMatch rule described in [RFC4530]. 1017 o The UuidOrderingMatch rule described in [RFC4530]. 1019 4.2.1.1. fedfsUuid 1021 A fedfsUuid is the base type for all of the universally unique 1022 identifiers (UUIDs) used by the federated filesystem protocols. 1024 The fedfsUuid type is based on rules and syntax defined in [RFC4530]. 1026 A fedfsUuid is a single-valued LDAP attribute. 1028 1029 /// 1030 /// attributetype ( 1031 /// 1.3.6.1.4.1.31103.1.1 NAME 'fedfsUuid' 1032 /// DESC 'A UUID used by NSDB' 1033 /// EQUALITY uuidMatch 1034 /// ORDERING uuidOrderingMatch 1035 /// SYNTAX 1.3.6.1.1.16.1 1036 /// SINGLE-VALUE 1037 /// ) 1038 /// 1040 1042 4.2.1.2. fedfsFsnUuid 1044 A fedfsFsnUuid represents the UUID component of an FSN. An NSDB 1045 SHOULD ensure that no two FSNs it stores have the same fedfsFsnUuid. 1047 This attribute is single-valued. 1049 1051 /// 1052 /// attributetype ( 1053 /// 1.3.6.1.4.1.31103.1.4 NAME 'fedfsFsnUuid' 1054 /// DESC 'The FSN UUID component of an FSN' 1055 /// SUP fedfsUuid 1056 /// SINGLE-VALUE 1057 /// ) 1058 /// 1060 1062 4.2.1.3. fedfsFsnTTL 1064 A fedfsFsnTTL is the time-to-live in seconds of a cached FSN and its 1065 child FSL records. It corresponds to the FsnTTL as defined in 1066 Section 2.7. See also Section Section 2.8.3 for information about 1067 caching FSLs. A fedfsFsnTTL MUST be encoded as an Integer syntax 1068 value [RFC4517] in the range [0, 4294967295]. 1070 This attribute is single-valued. 1072 1073 /// 1074 /// attributetype ( 1075 /// 1.3.6.1.4.1.31103.1.11 NAME 'fedfsFsnTTL' 1076 /// DESC 'Time to live of an FSN tree' 1077 /// EQUALITY integerMatch 1078 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1079 /// SINGLE-VALUE 1080 /// ) 1081 /// 1083 1085 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1087 4.2.1.4. fedfsNceDN 1089 A fedfsNceDN stores a distinguished name (DN). 1091 This attribute is single-valued. 1093 1095 /// 1096 /// attributetype ( 1097 /// 1.3.6.1.4.1.31103.1.14 NAME 'fedfsNceDN' 1098 /// DESC 'NCE Distinguished Name' 1099 /// EQUALITY distinguishedNameMatch 1100 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 1101 /// SINGLE-VALUE 1102 /// ) 1103 /// 1105 1107 OID 1.3.6.1.4.1.1466.115.121.1.12 is the DN syntax [RFC4517]. 1109 4.2.1.5. fedfsFslUuid 1111 A fedfsFslUuid represents the UUID of an FSL. An NSDB SHOULD ensure 1112 that no two FSLs it stores have the same fedfsFslUuid. 1114 This attribute is single-valued. 1116 1117 /// 1118 /// attributetype ( 1119 /// 1.3.6.1.4.1.31103.1.8 NAME 'fedfsFslUuid' 1120 /// DESC 'UUID of an FSL' 1121 /// SUP fedfsUuid 1122 /// SINGLE-VALUE 1123 /// ) 1124 /// 1126 1128 4.2.1.6. fedfsAnnotation 1130 A fedfsAnnotation contains an object annotation formatted as a key/ 1131 value pair. 1133 This attribute is multi-valued; an object type that permits 1134 annotations may have any number of annotations per instance. 1136 A fedfsAnnotation attribute is a human-readable sequence of UTF-8 1137 characters with no non-terminal NUL characters. The value MUST be 1138 formatted according to the following ABNF [RFC5234] rules: 1140 ANNOTATION = KEY "=" VALUE 1141 KEY = ITEM 1142 VALUE = ITEM 1143 ITEM = *WSP DQUOTE UTF8-octets DQUOTE *WSP 1145 DQUOTE and WSP are defined in [RFC5234], and UTF8-octets is defined 1146 in [RFC3629]. 1148 The following escape sequences are allowed: 1150 +-----------------+-------------+ 1151 | escape sequence | replacement | 1152 +-----------------+-------------+ 1153 | \\ | \ | 1154 | \" | " | 1155 +-----------------+-------------+ 1157 A fedfsAnnotation value might be processed as follows: 1159 1. Parse the attribute value according to the ANNOTATION rule, 1160 ignoring the escape sequences above. 1162 2. Scan through results of the previous step and replace the escape 1163 sequences above. 1165 A fedfsAnnotation attribute that does not adhere to this format 1166 SHOULD be ignored in its entirety. It MUST NOT prevent further 1167 processing of its containing entry. 1169 The following are examples of valid fedfsAnnotation attributes: 1171 "key1" = "foo" 1172 "another key" = "x=3" 1173 "key-2" = "A string with \" and \\ characters." 1174 "key3"="bar" 1176 which correspond to the following key/value pairs: 1178 +-------------+-----------------------------------+ 1179 | key | value | 1180 +-------------+-----------------------------------+ 1181 | key1 | foo | 1182 | another key | x=3 | 1183 | key-2 | A string with " and \ characters. | 1184 | key3 | bar | 1185 +-------------+-----------------------------------+ 1187 1189 /// 1190 /// attributetype ( 1191 /// 1.3.6.1.4.1.31103.1.12 NAME 'fedfsAnnotation' 1192 /// DESC 'Annotation of an object' 1193 /// SUP name 1194 /// ) 1195 /// 1197 1199 4.2.1.7. fedfsDescr 1201 A fedfsDescr stores an object description. The description MUST be 1202 encoded as a UTF-8 string. 1204 This attribute is multi-valued which permits any number of 1205 descriptions per entry. 1207 1208 /// 1209 /// attributetype ( 1210 /// 1.3.6.1.4.1.31103.1.13 NAME 'fedfsDescr' 1211 /// DESC 'Description of an object' 1212 /// SUP name 1213 /// ) 1214 /// 1216 1218 4.2.1.8. fedfsNfsURI 1220 A fedfsNfsURI stores the host and pathname components of an FSL. A 1221 fedfsNfsURI MUST be encoded as an NFS URI (see Section 2.8.1). 1223 The fedfsNfsURI is a subtype of the labeledURI type [RFC2079], with 1224 the same encoding rules. 1226 This attribute is single-valued. 1228 1230 /// 1231 /// attributetype ( 1232 /// 1.3.6.1.4.1.31103.1.120 NAME 'fedfsNfsURI' 1233 /// DESC 'Location of fileset' 1234 /// SUP labeledURI 1235 /// SINGLE-VALUE 1236 /// ) 1237 /// 1239 1241 4.2.1.9. fedfsNfsCurrency 1243 A fedfsNfsCurrency stores the NFSv4.1 fs_locations_server's 1244 fls_currency value [RFC5661]. A fedfsNfsCurrency MUST be encoded as 1245 an Integer syntax value [RFC4517] in the range [-2147483648, 1246 2147483647]. 1248 This attribute is single-valued. 1250 1251 /// 1252 /// attributetype ( 1253 /// 1.3.6.1.4.1.31103.1.103 NAME 'fedfsNfsCurrency' 1254 /// DESC 'up-to-date measure of the data' 1255 /// EQUALITY integerMatch 1256 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1257 /// SINGLE-VALUE 1258 /// ) 1259 /// 1261 1263 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1265 4.2.1.10. fedfsNfsGenFlagWritable 1267 A fedfsNfsGenFlagWritable stores the value of an FSL's NFSv4.1 1268 FSLI4GF_WRITABLE bit [RFC5661]. A value of "TRUE" indicates the bit 1269 is set. A value of "FALSE" indicates the bit is not set. 1271 1273 /// 1274 /// attributetype ( 1275 /// 1.3.6.1.4.1.31103.1.104 NAME 'fedfsNfsGenFlagWritable' 1276 /// DESC 'Indicates if the filesystem is writable' 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.11. fedfsNfsGenFlagGoing 1289 A fedfsNfsGenFlagGoing stores the value of an FSL's NFSv4.1 1290 FSLI4GF_GOING bit [RFC5661]. A value of "TRUE" indicates the bit is 1291 set. A value of "FALSE" indicates the bit is not set. 1293 1294 /// 1295 /// attributetype ( 1296 /// 1.3.6.1.4.1.31103.1.105 NAME 'fedfsNfsGenFlagGoing' 1297 /// DESC 'Indicates if the filesystem is going' 1298 /// EQUALITY booleanMatch 1299 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 1300 /// SINGLE-VALUE 1301 /// ) 1302 /// 1304 1306 OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517]. 1308 4.2.1.12. fedfsNfsGenFlagSplit 1310 A fedfsNfsGenFlagSplit stores the value of an FSL's NFSv4.1 1311 FSLI4GF_SPLIT bit [RFC5661]. A value of "TRUE" indicates the bit is 1312 set. A value of "FALSE" indicates the bit is not set. 1314 1316 /// 1317 /// attributetype ( 1318 /// 1.3.6.1.4.1.31103.1.106 NAME 'fedfsNfsGenFlagSplit' 1319 /// DESC 'Indicates if there are multiple filesystems' 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.13. fedfsNfsTransFlagRdma 1332 A fedfsNfsTransFlagRdma stores the value of an FSL's NFSv4.1 1333 FSLI4TF_RDMA bit [RFC5661]. A value of "TRUE" indicates the bit is 1334 set. A value of "FALSE" indicates the bit is not set. 1336 1337 /// 1338 /// attributetype ( 1339 /// 1.3.6.1.4.1.31103.1.107 NAME 'fedfsNfsTransFlagRdma' 1340 /// DESC 'Indicates if the transport supports RDMA' 1341 /// EQUALITY booleanMatch 1342 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 1343 /// SINGLE-VALUE 1344 /// ) 1345 /// 1347 1349 OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517]. 1351 4.2.1.14. fedfsNfsClassSimul 1353 A fedfsNfsClassSimul contains the FSL's NFSv4.1 FSLI4BX_CLSIMUL 1354 [RFC5661] value. A fedfsNfsClassSimul MUST be encoded as an Integer 1355 syntax value [RFC4517] in the range [0, 255]. 1357 1359 /// 1360 /// attributetype ( 1361 /// 1.3.6.1.4.1.31103.1.108 NAME 'fedfsNfsClassSimul' 1362 /// DESC 'The simultaneous-use 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.15. fedfsNfsClassHandle 1375 A fedfsNfsClassHandle contains the FSL's NFSv4.1 FSLI4BX_CLHANDLE 1376 [RFC5661] value. A fedfsNfsClassHandle MUST be encoded as an Integer 1377 syntax value [RFC4517] in the range [0, 255]. 1379 1380 /// 1381 /// attributetype ( 1382 /// 1.3.6.1.4.1.31103.1.109 NAME 'fedfsNfsClassHandle' 1383 /// DESC 'The handle class of the filesystem' 1384 /// EQUALITY integerMatch 1385 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1386 /// SINGLE-VALUE 1387 /// ) 1388 /// 1390 1392 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1394 4.2.1.16. fedfsNfsClassFileid 1396 A fedfsNfsClassFileid contains the FSL's NFSv4.1 FSLI4BX_CLFILEID 1397 [RFC5661] value. A fedfsNfsClassFileid MUST be encoded as an Integer 1398 syntax value [RFC4517] in the range [0, 255]. 1400 1402 /// 1403 /// attributetype ( 1404 /// 1.3.6.1.4.1.31103.1.110 NAME 'fedfsNfsClassFileid' 1405 /// DESC 'The fileid 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.17. fedfsNfsClassWritever 1418 A fedfsNfsClassWritever contains the FSL's NFSv4.1 FSLI4BX_CLWRITEVER 1419 [RFC5661] value. A fedfsNfsClassWritever MUST be encoded as an 1420 Integer syntax value [RFC4517] in the range [0, 255]. 1422 1423 /// 1424 /// attributetype ( 1425 /// 1.3.6.1.4.1.31103.1.111 NAME 'fedfsNfsClassWritever' 1426 /// DESC 'The write-verifier class of the filesystem' 1427 /// EQUALITY integerMatch 1428 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1429 /// SINGLE-VALUE 1430 /// ) 1431 /// 1433 1435 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1437 4.2.1.18. fedfsNfsClassChange 1439 A fedfsNfsClassChange contains the FSL's NFSv4.1 FSLI4BX_CLCHANGE 1440 [RFC5661] value. A fedfsNfsClassChange MUST be encoded as an Integer 1441 syntax value [RFC4517] in the range [0, 255]. 1443 1445 /// 1446 /// attributetype ( 1447 /// 1.3.6.1.4.1.31103.1.112 NAME 'fedfsNfsClassChange' 1448 /// DESC 'The change 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.19. fedfsNfsClassReaddir 1461 A fedfsNfsClassReaddir contains the FSL's NFSv4.1 FSLI4BX_CLREADDIR 1462 [RFC5661] value. A fedfsNfsClassReaddir MUST be encoded as an 1463 Integer syntax value [RFC4517] in the range [0, 255]. 1465 1466 /// 1467 /// attributetype ( 1468 /// 1.3.6.1.4.1.31103.1.113 NAME 'fedfsNfsClassReaddir' 1469 /// DESC 'The readdir class of the filesystem' 1470 /// EQUALITY integerMatch 1471 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1472 /// SINGLE-VALUE 1473 /// ) 1474 /// 1476 1478 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1480 4.2.1.20. fedfsNfsReadRank 1482 A fedfsNfsReadRank contains the FSL's NFSv4.1 FSLI4BX_READRANK 1483 [RFC5661] value. A fedfsNfsReadRank MUST be encoded as an Integer 1484 syntax value [RFC4517] in the range [0, 255]. 1486 1488 /// 1489 /// attributetype ( 1490 /// 1.3.6.1.4.1.31103.1.114 NAME 'fedfsNfsReadRank' 1491 /// DESC 'The read rank 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.21. fedfsNfsReadOrder 1504 A fedfsNfsReadOrder contains the FSL's NFSv4.1 FSLI4BX_READORDER 1505 [RFC5661] value. A fedfsNfsReadOrder MUST be encoded as an Integer 1506 syntax value [RFC4517] in the range [0, 255]. 1508 1509 /// 1510 /// attributetype ( 1511 /// 1.3.6.1.4.1.31103.1.115 NAME 'fedfsNfsReadOrder' 1512 /// DESC 'The read order of the filesystem' 1513 /// EQUALITY integerMatch 1514 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1515 /// SINGLE-VALUE 1516 /// ) 1517 /// 1519 1521 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1523 4.2.1.22. fedfsNfsWriteRank 1525 A fedfsNfsWriteRank contains the FSL's FSLI4BX_WRITERANK [RFC5661] 1526 value. A fedfsNfsWriteRank MUST be encoded as an Integer syntax 1527 value [RFC4517] in the range [0, 255]. 1529 1531 /// 1532 /// attributetype ( 1533 /// 1.3.6.1.4.1.31103.1.116 NAME 'fedfsNfsWriteRank' 1534 /// DESC 'The write rank 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.23. fedfsNfsWriteOrder 1547 A fedfsNfsWriteOrder contains the FSL's FSLI4BX_WRITEORDER [RFC5661] 1548 value. A fedfsNfsWriteOrder MUST be encoded as an Integer syntax 1549 value [RFC4517] in the range [0, 255]. 1551 1552 /// 1553 /// attributetype ( 1554 /// 1.3.6.1.4.1.31103.1.117 NAME 'fedfsNfsWriteOrder' 1555 /// DESC 'The write order of the filesystem' 1556 /// EQUALITY integerMatch 1557 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1558 /// SINGLE-VALUE 1559 /// ) 1560 /// 1562 1564 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1566 4.2.1.24. fedfsNfsVarSub 1568 A fedfsNfsVarSub stores the value of an FSL's NFSv4.1 FSLI4IF_VAR_SUB 1569 bit [RFC5661]. A value of "TRUE" indicates the bit is set. A value 1570 of "FALSE" indicates the bit is not set. 1572 1574 /// 1575 /// attributetype ( 1576 /// 1.3.6.1.4.1.31103.1.118 NAME 'fedfsNfsVarSub' 1577 /// DESC 'Indicates if variable substitution is present' 1578 /// EQUALITY booleanMatch 1579 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 1580 /// SINGLE-VALUE 1581 /// ) 1582 /// 1584 1586 OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517]. 1588 4.2.1.25. fedfsNfsValidFor 1590 A fedfsNfsValidFor stores an FSL's NFSv4.1 fs_locations_info 1591 fli_valid_for value [RFC5661]. A fedfsNfsValidFor MUST be encoded as 1592 an Integer syntax value [RFC4517] in the range [-2147483648, 1593 2147483647]. 1595 An FSL's parent's fedfsFsnTTL value and its fedfsNfsValidFor value 1596 MAY be different. 1598 This attribute is single-valued. 1600 1602 /// 1603 /// attributetype ( 1604 /// 1.3.6.1.4.1.31103.1.19 NAME 'fedfsNfsValidFor' 1605 /// DESC 'Valid for time' 1606 /// EQUALITY integerMatch 1607 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 1608 /// SINGLE-VALUE 1609 /// ) 1610 /// 1612 OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517]. 1614 1616 4.2.2. LDAP Object Classes 1618 4.2.2.1. fedfsNsdbContainerInfo 1620 A fedfsNsdbContainerInfo describes the location of the NCE. 1622 A fedfsNsdbContainerInfo's fedfsNceDN attribute is REQUIRED. 1624 A fedfsNsdbContainerInfo's fedfsAnnotation and fedfsDescr attributes 1625 are OPTIONAL. 1627 1629 /// 1630 /// objectclass ( 1631 /// 1.3.6.1.4.1.31103.1.1001 NAME 'fedfsNsdbContainerInfo' 1632 /// DESC 'Describes NCE location' 1633 /// SUP top AUXILIARY 1634 /// MUST ( 1635 /// fedfsNceDN 1636 /// ) 1637 /// MAY ( 1638 /// fedfsAnnotation 1639 /// $ fedfsDescr 1640 /// )) 1641 /// 1643 1645 4.2.2.2. fedfsFsn 1647 A fedfsFsn represents an FSN. 1649 A fedfsFsn's fedfsFsnUuid and fedfsFsnTTL attributes are REQUIRED. 1651 A fedfsFsn's fedfsAnnotation and fedfsDescr attributes are OPTIONAL. 1653 The DN of an FSN is REQUIRED to take the following form: 1654 "fedfsFsnUuid=$FSNUUID,$NCE", where $FSNUUID is the UUID of the FSN 1655 and $NCE is the DN of the NCE. Since LDAP requires a DN to be 1656 unique, this ensures that each FSN entry has a unique UUID value 1657 within the LDAP directory. 1659 1661 /// 1662 /// objectclass ( 1663 /// 1.3.6.1.4.1.31103.1.1002 NAME 'fedfsFsn' 1664 /// DESC 'Represents a fileset' 1665 /// SUP top STRUCTURAL 1666 /// MUST ( 1667 /// fedfsFsnUuid 1668 /// $ fedfsFsnTTL 1669 /// ) 1670 /// MAY ( 1671 /// fedfsAnnotation 1672 /// $ fedfsDescr 1673 /// )) 1674 /// 1676 1678 4.2.2.3. fedfsFsl 1680 The fedfsFsl object class represents an FSL. 1682 The fedfsFsl is an abstract object class. Protocol specific subtypes 1683 of this object class are used to store FSL information. The 1684 fedfsNfsFsl object class defined below is used to record an NFS FSL's 1685 location. Other subtypes MAY be defined for other protocols (e.g., 1686 CIFS). 1688 A fedfsFsl's fedfsFslUuid and fedfsFsnUuid attributes are REQUIRED. 1690 A fedfsFsl's fedfsAnnotation, and fedfsDescr attributes are OPTIONAL. 1692 The DN of an FSL is REQUIRED to take the following form: 1694 "fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE" where $FSLUUID is 1695 the FSL's UUID, $FSNUUID is the FSN's UUID, and $NCE is the DN of the 1696 NCE. Since LDAP requires a DN to be unique, this ensures that each 1697 FSL entry has a unique UUID value within the LDAP directory. 1699 1701 /// 1702 /// objectclass ( 1703 /// 1.3.6.1.4.1.31103.1.1003 NAME 'fedfsFsl' 1704 /// DESC 'A physical location of a fileset' 1705 /// SUP top ABSTRACT 1706 /// MUST ( 1707 /// fedfsFslUuid 1708 /// $ fedfsFsnUuid 1709 /// ) 1710 /// MAY ( 1711 /// fedfsAnnotation 1712 /// $ fedfsDescr 1713 /// )) 1714 /// 1716 1718 4.2.2.4. fedfsNfsFsl 1720 A fedfsNfsFsl is used to represent an NFS FSL. The fedfsNfsFsl 1721 inherits all of the attributes of the fedfsFsl and extends the 1722 fedfsFsl with information specific to the NFS protocol. 1724 The DN of an NFS FSL is REQUIRED to take the following form: 1725 "fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE" where $FSLUUID is 1726 the FSL's UUID, $FSNUUID is the FSN's UUID, and $NCE is the DN of the 1727 NCE. Since LDAP requires a DN to be unique, this ensures that each 1728 NFS FSL entry has a unique UUID value within the LDAP directory. 1730 1731 /// 1732 /// objectclass ( 1733 /// 1.3.6.1.4.1.31103.1.1004 NAME 'fedfsNfsFsl' 1734 /// DESC 'An NFS location of a fileset' 1735 /// SUP fedfsFsl STRUCTURAL 1736 /// MUST ( 1737 /// fedfsNfsURI 1738 /// $ fedfsNfsCurrency 1739 /// $ fedfsNfsGenFlagWritable 1740 /// $ fedfsNfsGenFlagGoing 1741 /// $ fedfsNfsGenFlagSplit 1742 /// $ fedfsNfsTransFlagRdma 1743 /// $ fedfsNfsClassSimul 1744 /// $ fedfsNfsClassHandle 1745 /// $ fedfsNfsClassFileid 1746 /// $ fedfsNfsClassWritever 1747 /// $ fedfsNfsClassChange 1748 /// $ fedfsNfsClassReaddir 1749 /// $ fedfsNfsReadRank 1750 /// $ fedfsNfsReadOrder 1751 /// $ fedfsNfsWriteRank 1752 /// $ fedfsNfsWriteOrder 1753 /// $ fedfsNfsVarSub 1754 /// $ fedfsNfsValidFor 1755 /// )) 1756 /// 1758 1760 5. NSDB Operations 1762 The operations defined by the protocol can be described as several 1763 sub-protocols that are used by entities within a federation to 1764 perform different roles. 1766 The first of these sub-protocols defines how the state of an NSDB 1767 node can be initialized and updated. The primary use of this sub- 1768 protocol is by an administrator to add, edit, or delete filesets, 1769 their properties, and their fileset locations. 1771 The second of these sub-protocols defines the queries that are sent 1772 to an NSDB node in order to perform resolution (or to find other 1773 information about the data stored within that NSDB node) and the 1774 responses returned by the NSDB node. The primary use of this sub- 1775 protocol is by a fileserver in order to perform resolution, but it 1776 may also be used by an administrator to query the state of the 1777 system. 1779 The first and second sub-protocols are defined as LDAP operations, 1780 using the schema defined in the previous section. If each NSDB node 1781 is a standard LDAP server, then, in theory, it is unnecessary to 1782 describe the LDAP operations in detail, because the operations are 1783 ordinary LDAP operations to query and update records. However, we do 1784 not require that an NSDB node implement a complete LDAP service, and 1785 therefore we define in these sections the minimum level of LDAP 1786 functionality required to implement an NSDB node. 1788 The NSDB sub-protocols are defined in Section 5.1 and Section 5.2. 1789 The descriptions of LDAP messages in these sections use the LDAP Data 1790 Interchange Format (LDIF) [RFC2849]. In order to differentiate 1791 constant and variable strings in the LDIF specifications, variables 1792 are prefixed by a $ character and use all upper case characters. For 1793 example, a variable named FOO would be specified as $FOO. 1795 This document uses the term NSDB client to refer to an LDAP client 1796 that uses either of the NSDB sub-protocols. 1798 The third sub-protocol defines the queries and other requests that 1799 are sent to a fileserver in order to get information from it or to 1800 modify the state of the fileserver in a manner related to the 1801 federation protocols. The primary purpose of this protocol is for an 1802 administrator to create or delete a junction or discover related 1803 information about a particular fileserver. 1805 The third sub-protocol is defined as an ONC RPC protocol. The reason 1806 for using ONC RPC instead of LDAP is that all fileservers support ONC 1807 RPC but some do not support an LDAP Directory server. 1809 The ONC RPC administration protocol is defined in [FEDFS-ADMIN]. 1811 5.1. NSDB Operations for Administrators 1813 The admin entity initiates and controls the commands to manage 1814 fileset and namespace information. The protocol used for 1815 communicating between the admin entity and each NSDB node MUST be the 1816 LDAPv3 [RFC4510] protocol. 1818 The names we assign to these operations are entirely for the purpose 1819 of exposition in this document, and are not part of the LDAP dialogs. 1821 5.1.1. Create an FSN 1823 This operation creates a new FSN in the NSDB by adding a new fedfsFsn 1824 entry in the NSDB's LDAP directory. 1826 A fedfsFsn entry contains a fedfsFsnUuid. The administrator chooses 1827 the fedfsFsnUuid by a process described in Section 2.12). A fedfsFsn 1828 entry also contains a fedfsFsnTTL. The fedfsFsnTTL is chosen by the 1829 administrator as described in Section 2.8.3. 1831 5.1.1.1. LDAP Request 1833 This operation is implemented using the LDAP ADD request described by 1834 the LDIF below. 1836 dn: fedfsFsnUuid=$FSNUUID,$NCE 1837 changeType: add 1838 objectClass: fedfsFsn 1839 fedfsFsnUuid: $FSNUUID 1840 fedfsFsnTTL: $TTL 1842 For example, if the $FSNUUID is "e8c4761c-eb3b-4307-86fc- 1843 f702da197966", the $TTL is "300" seconds, and the $NCE is "o=fedfs" 1844 the operation would be: 1846 dn: fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs 1847 changeType: add 1848 objectClass: fedfsFsn 1849 fedfsFsnUuid: e8c4761c-eb3b-4307-86fc-f702da197966 1850 fedfsFsnTTL: 300 1852 5.1.2. Delete an FSN 1854 This operation deletes an FSN by removing a fedfsFsn entry in the 1855 NSDB's LDAP directory. 1857 If the FSN entry being deleted has child FSL entries, this function 1858 MUST return an error. This ensures that the NSDB will not contain 1859 any orphaned FSL entries. A compliant LDAP implementation will meet 1860 this requirement since Section 4.8 of [RFC4511] defines the LDAP 1861 delete operation to only be capable of removing leaf entries. 1863 Note that the FSN delete function removes the fileset only from a 1864 federation namespace (by removing the records for that FSN from the 1865 NSDB node that receives this request). The fileset and its data are 1866 not deleted. Any junction that has this FSN as its target may 1867 continue to point to this non-existent FSN. A dangling reference may 1868 be detected when a fileserver tries to resolve a junction that refers 1869 to the deleted FSN. 1871 5.1.2.1. LDAP Request 1873 This operation is implemented using the LDAP DELETE request described 1874 by the LDIF below. 1876 dn: fedfsFsnUuid=$FSNUUID,$NCE 1877 changeType: delete 1879 For example, if the $FSNUUID is "e8c4761c-eb3b-4307-86fc- 1880 f702da197966" and $NCE is "o=fedfs", the operation would be: 1882 dn: fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs 1883 changeType: delete 1885 5.1.3. Create an FSL 1887 This operation creates a new FSL for the given FSN by adding a new 1888 fedfsFsl entry in the NSDB's LDAP directory. 1890 A fedfsFsl entry contains a fedfsFslUuid and fedfsFsnUuid. The 1891 administrator chooses the fedfsFslUuid. The process for choosing the 1892 fedfsFslUuid is described in Section 2.12. The fedfsFsnUuid is the 1893 UUID of the FSL's FSN. 1895 The administrator will also set additional attributes depending on 1896 the FSL type. 1898 5.1.3.1. LDAP Request 1900 This operation is implemented using the LDAP ADD request described by 1901 the LDIF below (NOTE: the LDIF shows the creation of an NFS FSL) 1902 dn: fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE 1903 changeType: add 1904 objectClass: fedfsNfsFsl 1905 fedfsFslUuid: $FSLUUID 1906 fedfsFsnUuid: $FSNUUID 1907 fedfsNfsURI: nfs://$HOST:$PORT//$PATH 1908 fedfsNfsCurrency: $CURRENCY 1909 fedfsNfsGenFlagWritable: $WRITABLE 1910 fedfsNfsGenFlagGoing: $GOING 1911 fedfsNfsGenFlagSplit: $SPLIT 1912 fedfsNfsTransFlagRdma: $RDMA 1913 fedfsNfsClassSimul: $CLASS_SIMUL 1914 fedfsNfsClassHandle:$CLASS_HANDLE 1915 fedfsNfsClassFileid:$CLASS_FILEID 1916 fedfsNfsClassWritever:$CLASS_WRITEVER 1917 fedfsNfsClassChange: $CLASS_CHANGE 1918 fedfsNfsClassReaddir: $CLASS_READDIR 1919 fedfsNfsReadRank: $READ_RANK 1920 fedfsNfsReadOrder: $READ_ORDER 1921 fedfsNfsWriteRank: $WRITE_RANK 1922 fedfsNfsWriteOrder: $WRITE_ORDER 1923 fedfsNfsVarSub: $VAR_SUB 1924 fedfsNfsValidFor: $TIME 1925 fedfsAnnotation: $ANNOTATION 1926 fedfsDescr: $DESCR 1928 For example, if the $FSNUUID is "e8c4761c-eb3b-4307-86fc- 1929 f702da197966", the $FSLUUID is "ba89a802-41a9-44cf-8447- 1930 dda367590eb3", the $HOST is "server.example.com", $PORT is "20049", 1931 the $PATH is stored in the file "/tmp/fsl_path", $CURRENCY is "0" (an 1932 up-to-date copy), the FSL is writable, but not going, split, or 1933 accessible via RDMA, the simultaneous-use class is "1", the handle 1934 class is "0", the fileid class is "1", the write-verifier class is 1935 "1", the change class is "1", the readdir class is "9", the read rank 1936 is "7", the read order is "8", the write rank is "5", the write order 1937 is "6", variable substitution is false, $TIME is "300" seconds, 1938 $ANNOTATION is ""foo" = "bar"", $DESC is "This is a description.", 1939 and the $NCE is "o=fedfs", the operation would be (for readability 1940 the DN is split into two lines): 1942 dn: fedfsFslUuid=ba89a802-41a9-44cf-8447-dda367590eb3, 1943 fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs 1944 changeType: add 1945 objectClass: fedfsNfsFsl 1946 fedfsFslUuid: ba89a802-41a9-44cf-8447-dda367590eb3 1947 fedfsFsnUuid: e8c4761c-eb3b-4307-86fc-f702da197966 1948 fedfsNfsURI: nfs://server.example.com:20049//tmp/fsl_path 1949 fedfsNfsCurrency: 0 1950 fedfsNfsGenFlagWritable: TRUE 1951 fedfsNfsGenFlagGoing: FALSE 1952 fedfsNfsGenFlagSplit: FALSE 1953 fedfsNfsTransFlagRdma: FALSE 1954 fedfsNfsClassSimul: 1 1955 fedfsNfsClassHandle: 0 1956 fedfsNfsClassFileid: 1 1957 fedfsNfsClassWritever: 1 1958 fedfsNfsClassChange: 1 1959 fedfsNfsClassReaddir: 9 1960 fedfsNfsReadRank: 7 1961 fedfsNfsReadOrder: 8 1962 fedfsNfsWriteRank: 5 1963 fedfsNfsWriteOrder: 6 1964 fedfsNfsVarSub: FALSE 1965 fedfsNfsValidFor: 300 1966 fedfsAnnotation: "foo" = "bar" 1967 fedfsDescr: This is a description. 1969 5.1.3.2. Selecting fedfsNfsFsl Values 1971 The fedfsNfsFSl object class is used to describe NFSv4 accessible 1972 filesets. For the reasons described in Section 2.8.4, administrators 1973 SHOULD choose reasonable values for all LDAP attributes of an NFSv4 1974 accessible fedfsNfsFsl even though some of these LDAP attributes are 1975 not explicitly contained in an NFSv4 fs_locations attribute. 1977 When the administrator is unable to choose reasonable values for the 1978 LDAP attributes not explicitly contained in an NFSv4 fs_locations 1979 attribute, the values in the following table are RECOMMENDED. 1981 +-------------------------+----------+------------------------------+ 1982 | LDAP attribute | LDAP | Notes | 1983 | | value | | 1984 +-------------------------+----------+------------------------------+ 1985 | fedfsNfsCurrency | negative | Indicates that the server | 1986 | | value | does not know the currency | 1987 | | | (see 11.10.1 of [RFC5661]). | 1988 | fedfsNfsGenFlagWritable | FALSE | Leaving unset is not harmful | 1989 | | | (see 11.10.1 of [RFC5661]). | 1990 | fedfsNfsGenFlagGoing | FALSE | NFS client will detect a | 1991 | | | migration event if the FSL | 1992 | | | becomes unavailable. | 1993 | fedfsNfsGenFlagSplit | TRUE | Safe to assume that the FSL | 1994 | | | is split. | 1995 | fedfsNfsTransFlagRdma | TRUE | NFS client will detect if | 1996 | | | RDMA access is available. | 1997 | fedfsNfsClassSimul | 0 | 0 is treated as non-matching | 1998 | | | (see 11.10.1 of [RFC5661]). | 1999 | fedfsNfsClassHandle | 0 | See fedfsNfsClassSimul note. | 2000 | fedfsNfsClassFileid | 0 | See fedfsNfsClassSimul note. | 2001 | fedfsNfsClassWritever | 0 | See fedfsNfsClassSimul note. | 2002 | fedfsNfsClassChange | 0 | See fedfsNfsClassSimul note. | 2003 | fedfsNfsClassReaddir | 0 | See fedfsNfsClassSimul note. | 2004 | fedfsNfsReadRank | 0 | Highest value ensures FSL | 2005 | | | will be tried. | 2006 | fedfsNfsReadOrder | 0 | See fedfsNfsReadRank note. | 2007 | fedfsNfsWriteRank | 0 | See fedfsNfsReadRank note. | 2008 | fedfsNfsWriteOrder | 0 | See fedfsNfsReadRank note. | 2009 | fedfsNfsVarSub | FALSE | NFSv4 does not define | 2010 | | | variable substitution in | 2011 | | | paths. | 2012 | fedfsNfsValidFor | 0 | Indicates no appropriate | 2013 | | | refetch interval (see | 2014 | | | 11.10.2 of [RFC5661]). | 2015 +-------------------------+----------+------------------------------+ 2017 5.1.4. Delete an FSL 2019 This operation deletes an FSL record. The admin requests the NSDB 2020 node storing the fedfsFsl to delete it from its database. This 2021 operation does not result in fileset data being deleted on any 2022 fileserver. 2024 5.1.4.1. LDAP Request 2026 The admin sends an LDAP DELETE request to the NSDB node to remove the 2027 FSL. 2029 dn: fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE 2030 changeType: delete 2032 For example, if the $FSNUUID is "e8c4761c-eb3b-4307-86fc- 2033 f702da197966", the $FSLUUID is "ba89a802-41a9-44cf-8447- 2034 dda367590eb3", and the $NCE is "o=fedfs", the operation would be (for 2035 readability the DN is split into two lines): 2037 dn: fedfsFslUuid=ba89a802-41a9-44cf-8447-dda367590eb3, 2038 fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs 2039 changeType: delete 2041 5.1.5. Update an FSL 2043 This operation updates the attributes of a given FSL. This command 2044 results in a change in the attributes of the fedfsFsl at the NSDB 2045 node maintaining this FSL. The values of the fedfsFslUuid and 2046 fedfsFsnUuid attributes MUST NOT change during an FSL update. 2048 5.1.5.1. LDAP Request 2050 The admin sends an LDAP MODIFY request to the NSDB node to update the 2051 FSL. 2053 dn: fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE 2054 changeType: modify 2055 replace: $ATTRIBUTE-TYPE 2057 For example, if the $FSNUUID is "e8c4761c-eb3b-4307-86fc- 2058 f702da197966", the $FSLUUID is "ba89a802-41a9-44cf-8447- 2059 dda367590eb3", the $NCE is "o=fedfs", and the administrator wished to 2060 change the NFS read rank to 10, the operation would be (for 2061 readability the DN is split into two lines): 2063 dn: fedfsFslUuid=ba89a802-41a9-44cf-8447-dda367590eb3, 2064 fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs 2065 changeType: modify 2066 replace: fedfsNfsReadClass 2067 fedfsNfsReadRank: 10 2069 5.2. NSDB Operations for Fileservers 2071 5.2.1. NSDB Container Entry (NCE) Enumeration 2073 To find the NCEs for the NSDB nsdb.example.com, a fileserver would do 2074 the following: 2076 nce_list = empty 2077 connect to the LDAP directory at nsdb.example.com 2078 for each namingContext value $BAR in the root DSE 2079 /* $BAR is a DN */ 2080 query for a fedfsNceDN value at $BAR 2081 /* 2082 * The RFC 4516 LDAP URL for this search would be 2083 * 2084 * ldap://nsdb.example.com:389/$BAR?fedfsNceDN?? 2085 * (objectClass=fedfsNsdbContainerInfo) 2086 * 2087 */ 2088 if a fedfsNceDN value is found 2089 add the value to the nce_list 2091 5.2.2. Lookup FSLs for an FSN 2093 Using an LDAP search, the fileserver can obtain all of the FSLs for a 2094 given FSN. The FSN's fedfsFsnUuid is used as the search key. The 2095 following examples use the LDAP Universal Resource Identifier (URI) 2096 format defined in [RFC4516]. 2098 To obtain a list of all FSLs for $FSNUUID on the NSDB named 2099 $NSDBNAME, the following search can be used (for readability the URI 2100 is split into two lines): 2102 for each $NCE in nce_list 2103 ldap://$NSDBNAME/fsnUuid=$FSNUUID,$NCE??one? 2104 (objectClass=fedfsFsl) 2106 This search is for the children of the object with DN 2107 "fedfsFsnUuid=$FSNUUID,$NCE" with a filter for 2108 "objectClass=fedfsFsl". The scope value of "one" restricts the 2109 search to the entry's children (rather than the entire subtree below 2110 the entry) and the filter ensures that only FSL entries are returned. 2112 For example if $NSDBNAME is "nsdb.example.com", $FSNUUID is 2113 "e8c4761c-eb3b-4307-86fc-f702da197966", and $NCE is "o=fedfs", the 2114 search would be (for readability the URI is split into three lines): 2116 ldap://nsdb.example.com/ 2117 fsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs 2118 ??one?(objectClass=fedfsFsl) 2120 The following search can be used to obtain only the NFS FSLs for 2121 $FSNUUID on the NSDB named $NSDBNAME (for readability the URI is 2122 split into two lines): 2124 for each $NCE in nce_list 2125 ldap://$NSDBNAME/fsnUuid=$FSNUUID,$NCE??one? 2126 (objectClass=fedfsNfsFsl) 2128 This also searches for the children of the object with DN 2129 "fedfsFsnUuid=$FSNUUID,$NCE", but the filter for "objectClass = 2130 fedfsNfsFsl" restricts the results to only NFS FSLs. 2132 For example if $NSDBNAME is nsdb.example.com, $FSNUUID is "e8c4761c- 2133 eb3b-4307-86fc-f702da197966", and $NCE is "o=fedfs",the search would 2134 be (for readability the URI is split into three lines): 2136 ldap://nsdb.example.com/ 2137 fsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs 2138 ??one?(objectClass=fedfsNfsFsl) 2140 The fileserver will generate a referral based on the set of FSLs 2141 returned by these queries using the process described in 2142 Section 2.8.4. 2144 5.3. NSDB Operations and LDAP Referrals 2146 The LDAPv3 protocol defines an LDAP referral mechanism that allows an 2147 LDAP server to redirect an LDAP client. LDAPv3 defines two types of 2148 LDAP referrals: the Referral type defined in Section 4.1.10 of 2149 [RFC4511] and the SearchResultReference type defined in Section 4.5.3 2150 of [RFC4511]. In both cases, the LDAP referral lists one or more 2151 URIs for services that can be used to complete the operation. In the 2152 remainder of this document, the term LDAP referral is used to 2153 indicate either of these types. 2155 If an NSDB operation results in an LDAP referral, the NSDB client MAY 2156 follow the LDAP referral. An NSDB client's decision to follow an 2157 LDAP referral is implementation and configuration dependent. For 2158 example, an NSDB client might be configured to follow only those LDAP 2159 referrals that were received over a secure channel, or only those 2160 that target an NSDB that supports encrypted communication. If an 2161 NSDB client chooses to follow an LDAP referral, the NSDB client MUST 2162 process the LDAP referral and prevent looping as described in Section 2163 4.1.10 of [RFC4511]. 2165 6. Security Considerations 2167 Both the NFSv4 and LDAPv3 protocols provide security mechanisms. 2168 When used in conjunction with the federated filesystem protocols 2169 described in this document, the use of these mechanisms is 2170 RECOMMENDED. Specifically, the use of RPCSEC_GSS [RFC2203], which is 2171 built on the GSS-API [RFC2743], is RECOMMENDED on all NFS connections 2172 between a file-access client and fileserver. The "Security 2173 Considerations" sections of the NFSv4.0 [3530bis] and NFSv4.1 2174 [RFC5661] specifications contain special considerations for the 2175 handling of GETATTR operations for the fs_locations and 2176 fs_locations_info attributes. 2178 NSDB nodes and NSDB clients MUST implement support for TLS [RFC5246], 2179 as described in [RFC4513]. For all LDAP connections established by 2180 the federated filesystem protocols, the use of TLS is RECOMMENDED. 2182 If an NSDB client chooses to follow an LDAP referral, the NSDB client 2183 SHOULD authenticate the LDAP referral's target NSDB using the target 2184 NSDB's credentials (not the credentials of the NSDB that generated 2185 the LDAP referral). The NSDB client SHOULD NOT follow an LDAP 2186 referral that targets an NSDB for which it does not know the NSDB's 2187 credentials. 2189 Within a federation, there are two types of components an attacker 2190 may compromise: a fileserver and an NSDB. 2192 If an attacker compromises a fileserver, the attacker can interfere 2193 with a file-access client's filesystem I/O operations (e.g., by 2194 returning fictitious data in the response to a read request) or 2195 fabricating a referral. The attacker's abilities are the same 2196 regardless of whether or not the federation protocols are in use. 2197 While the federation protocols do not give the attacker additional 2198 capabilities, they are additional targets for attack. The LDAP 2199 protocol described in Section 5.2 SHOULD be secured using the methods 2200 described above to defeat attacks on a fileserver via this channel. 2202 If an attacker compromises an NSDB, the attacker will be able to 2203 forge FSL information and thus poison the fileserver's referral 2204 information. Therefore an NSDB should be as secure as the 2205 fileservers which query it. The LDAP operations described in 2206 Section 5 SHOULD be secured using the methods described above to 2207 defeat attacks on an NSDB via this channel. 2209 A fileserver binds anonymously when performing NSDB operations. Thus 2210 the contents and distinguished names of FSN and FSL records are 2211 required to be readable by anyone who can bind anonymously to an NSDB 2212 service. Section 2.12 presents the security considerations in the 2213 choice of the type of UUID used in these records. 2215 It should be noted that the federation protocols do not directly 2216 provide access to filesystem data. The federation protocols only 2217 provide a mechanism for building a namespace. All data transfers 2218 occur between a file-access client and fileserver just as they would 2219 if the federation protocols were not in use. As a result, the 2220 federation protocols do not require new user authentication and 2221 authorization mechanisms or require a fileserver to act as a proxy 2222 for a client. 2224 7. IANA Considerations 2226 7.1. Registry for the fedfsAnnotation Key Namespace 2228 This document defines the fedfsAnnotation key in Section 4.2.1.6. 2229 The fedfsAnnotation key namespace is to be managed by IANA. IANA is 2230 to create and maintain a new registry entitled "FedFS Annotation 2231 Keys". The location of this registry should be under a new heading 2232 called "Federated File System (FedFS) Parameters". The URL address 2233 can be based off of the new heading name, for example: 2234 http://www.iana.org/assignments/fedfs-parameters/ ... 2236 Future registrations are to be administered by IANA using the "First 2237 Come First Served" policy defined in [RFC5226]. Registration 2238 requests MUST include the key (a valid UTF-8 string of any length), a 2239 brief description of the key's purpose, and an email contact for the 2240 registration. For viewing, the registry should be sorted 2241 lexicographically by key. There are no initial assignments for this 2242 registry. 2244 7.2. Registry for FedFS Object Identifiers 2246 Using the process described in [RFC2578], one of the authors was 2247 assigned the Internet Private Enterprise Numbers range 2248 1.3.6.1.4.1.31103.x. Within this range, the subrange 2249 1.3.6.1.4.1.31103.1.x is permanently dedicated for use by the 2250 federated file system protocols. Unassigned OIDs in this range MAY 2251 be used for Private Use or Experimental Use as defined in [RFC5226]. 2252 New permanent FedFS OID assignments MUST NOT be made using OIDs in 2253 this range. 2255 IANA is to create and maintain a new registry entitled "FedFS Object 2256 Identifiers" for the purpose of recording the allocations of FedFS 2257 Object Identifiers (OIDs) specified by this document. No future 2258 allocations in this registry are allowed. 2260 The location of this registry should be under the heading "Federated 2261 File System (FedFS) Parameters", created in Section 7.1. The URL 2262 address can be based off of the new heading name, for example: 2263 http://www.iana.org/assignments/fedfs-parameters/ ... 2265 For viewing, the registry should be sorted numerically by OID value. 2266 The contents of the FedFS Object Identifiers registry are given in 2267 Table 1. 2269 Note: A descriptor designated below as "historic" reserves an OID 2270 used in a past version of the NSDB protocol. Registering such OIDs 2271 retains compatibility among existing implementations of the NSDB 2272 protocol. This document does not otherwise refer to historic OIDs. 2274 +--------------------------+-------------------------+-----------+ 2275 | OID | Description | Reference | 2276 +--------------------------+-------------------------+-----------+ 2277 | 1.3.6.1.4.1.31103.1.1 | fedfsUuid | RFC-TBD1 | 2278 | 1.3.6.1.4.1.31103.1.2 | fedfsNetAddr | historic | 2279 | 1.3.6.1.4.1.31103.1.3 | fedfsNetPort | historic | 2280 | 1.3.6.1.4.1.31103.1.4 | fedfsFsnUuid | RFC-TBD1 | 2281 | 1.3.6.1.4.1.31103.1.5 | fedfsNsdbName | historic | 2282 | 1.3.6.1.4.1.31103.1.6 | fedfsNsdbPort | historic | 2283 | 1.3.6.1.4.1.31103.1.7 | fedfsNcePrefix | historic | 2284 | 1.3.6.1.4.1.31103.1.8 | fedfsFslUuid | RFC-TBD1 | 2285 | 1.3.6.1.4.1.31103.1.9 | fedfsFslHost | historic | 2286 | 1.3.6.1.4.1.31103.1.10 | fedfsFslPort | historic | 2287 | 1.3.6.1.4.1.31103.1.11 | fedfsFslTTL | historic | 2288 | 1.3.6.1.4.1.31103.1.12 | fedfsAnnotation | RFC-TBD1 | 2289 | 1.3.6.1.4.1.31103.1.13 | fedfsDescr | RFC-TBD1 | 2290 | 1.3.6.1.4.1.31103.1.14 | fedfsNceDN | RFC-TBD1 | 2291 | 1.3.6.1.4.1.31103.1.15 | fedfsFsnTTL | RFC-TBD1 | 2292 | 1.3.6.1.4.1.31103.1.100 | fedfsNfsPath | historic | 2293 | 1.3.6.1.4.1.31103.1.101 | fedfsNfsMajorVer | historic | 2294 | 1.3.6.1.4.1.31103.1.102 | fedfsNfsMinorVer | historic | 2295 | 1.3.6.1.4.1.31103.1.103 | fedfsNfsCurrency | RFC-TBD1 | 2296 | 1.3.6.1.4.1.31103.1.104 | fedfsNfsGenFlagWritable | RFC-TBD1 | 2297 | 1.3.6.1.4.1.31103.1.105 | fedfsNfsGenFlagGoing | RFC-TBD1 | 2298 | 1.3.6.1.4.1.31103.1.106 | fedfsNfsGenFlagSplit | RFC-TBD1 | 2299 | 1.3.6.1.4.1.31103.1.107 | fedfsNfsTransFlagRdma | RFC-TBD1 | 2300 | 1.3.6.1.4.1.31103.1.108 | fedfsNfsClassSimul | RFC-TBD1 | 2301 | 1.3.6.1.4.1.31103.1.109 | fedfsNfsClassHandle | RFC-TBD1 | 2302 | 1.3.6.1.4.1.31103.1.110 | fedfsNfsClassFileid | RFC-TBD1 | 2303 | 1.3.6.1.4.1.31103.1.111 | fedfsNfsClassWritever | RFC-TBD1 | 2304 | 1.3.6.1.4.1.31103.1.112 | fedfsNfsClassChange | RFC-TBD1 | 2305 | 1.3.6.1.4.1.31103.1.113 | fedfsNfsClassReaddir | RFC-TBD1 | 2306 | 1.3.6.1.4.1.31103.1.114 | fedfsNfsReadRank | RFC-TBD1 | 2307 | 1.3.6.1.4.1.31103.1.115 | fedfsNfsReadOrder | RFC-TBD1 | 2308 | 1.3.6.1.4.1.31103.1.116 | fedfsNfsWriteRank | RFC-TBD1 | 2309 | 1.3.6.1.4.1.31103.1.117 | fedfsNfsWriteOrder | RFC-TBD1 | 2310 | 1.3.6.1.4.1.31103.1.118 | fedfsNfsVarSub | RFC-TBD1 | 2311 | 1.3.6.1.4.1.31103.1.119 | fedfsNfsValidFor | RFC-TBD1 | 2312 | 1.3.6.1.4.1.31103.1.120 | fedfsNfsURI | RFC-TBD1 | 2313 | 1.3.6.1.4.1.31103.1.1001 | fedfsNsdbContainerInfo | RFC-TBD1 | 2314 | 1.3.6.1.4.1.31103.1.1002 | fedfsFsn | RFC-TBD1 | 2315 | 1.3.6.1.4.1.31103.1.1003 | fedfsFsl | RFC-TBD1 | 2316 | 1.3.6.1.4.1.31103.1.1004 | fedfsNfsFsl | RFC-TBD1 | 2317 +--------------------------+-------------------------+-----------+ 2319 Table 1 2321 7.3. LDAP Descriptor Registration 2323 In accordance with Section 3.4 and Section 4 of [RFC4520], the object 2324 identifier descriptors defined in this document (listed below) will 2325 be registered via the Expert Review process. 2327 Subject: Request for LDAP Descriptor Registration 2328 Person & email address to contact for further information: See 2329 "Author/Change Controller" 2330 Specification: draft-ietf-nfsv4-federated-fs-protocol 2331 Author/Change Controller: IESG (iesg@ietf.org) 2333 Object Identifier: 1.3.6.1.4.1.31103.1.1 2334 Descriptor (short name): fedfsUuid 2335 Usage: attribute type 2337 Object Identifier: 1.3.6.1.4.1.31103.1.2 2338 Descriptor (short name): fedfsNetAddr 2339 Usage: attribute type (historic) 2341 Object Identifier: 1.3.6.1.4.1.31103.1.3 2342 Descriptor (short name): fedfsNetPort 2343 Usage: attribute type (historic) 2345 Object Identifier: 1.3.6.1.4.1.31103.1.4 2346 Descriptor (short name): fedfsFsnUuid 2347 Usage: attribute type 2349 Object Identifier: 1.3.6.1.4.1.31103.1.5 2350 Descriptor (short name): fedfsNsdbName 2351 Usage: attribute type (historic) 2353 Object Identifier: 1.3.6.1.4.1.31103.1.6 2354 Descriptor (short name): fedfsNsdbPort 2355 Usage: attribute type (historic) 2357 Object Identifier: 1.3.6.1.4.1.31103.1.7 2358 Descriptor (short name): fedfsNcePrefix 2359 Usage: attribute type (historic) 2361 Object Identifier: 1.3.6.1.4.1.31103.1.8 2362 Descriptor (short name): fedfsFslUuid 2363 Usage: attribute type 2364 Object Identifier: 1.3.6.1.4.1.31103.1.9 2365 Descriptor (short name): fedfsFslHost 2366 Usage: attribute type (historic) 2368 Object Identifier: 1.3.6.1.4.1.31103.1.10 2369 Descriptor (short name): fedfsFslPort 2370 Usage: attribute type (historic) 2372 Object Identifier: 1.3.6.1.4.1.31103.1.11 2373 Descriptor (short name): fedfsFslTTL 2374 Usage: attribute type (historic) 2376 Object Identifier: 1.3.6.1.4.1.31103.1.12 2377 Descriptor (short name): fedfsAnnotation 2378 Usage: attribute type 2380 Object Identifier: 1.3.6.1.4.1.31103.1.13 2381 Descriptor (short name): fedfsDescr 2382 Usage: attribute type 2384 Object Identifier: 1.3.6.1.4.1.31103.1.14 2385 Descriptor (short name): fedfsNceDN 2386 Usage: attribute type 2388 Object Identifier: 1.3.6.1.4.1.31103.1.15 2389 Descriptor (short name): fedfsFsnTTL 2390 Usage: attribute type 2392 Object Identifier: 1.3.6.1.4.1.31103.1.100 2393 Descriptor (short name): fedfsNfsPath 2394 Usage: attribute type (historic) 2396 Object Identifier: 1.3.6.1.4.1.31103.1.101 2397 Descriptor (short name): fedfsNfsMajorVer 2398 Usage: attribute type (historic) 2400 Object Identifier: 1.3.6.1.4.1.31103.1.102 2401 Descriptor (short name): fedfsNfsMinorVer 2402 Usage: attribute type (historic) 2404 Object Identifier: 1.3.6.1.4.1.31103.1.103 2405 Descriptor (short name): fedfsNfsCurrency 2406 Usage: attribute type 2407 Object Identifier: 1.3.6.1.4.1.31103.1.104 2408 Descriptor (short name): fedfsNfsGenFlagWritable 2409 Usage: attribute type 2411 Object Identifier: 1.3.6.1.4.1.31103.1.105 2412 Descriptor (short name): fedfsNfsGenFlagGoing 2413 Usage: attribute type 2415 Object Identifier: 1.3.6.1.4.1.31103.1.106 2416 Descriptor (short name): fedfsNfsGenFlagSplit 2417 Usage: attribute type 2419 Object Identifier: 1.3.6.1.4.1.31103.1.107 2420 Descriptor (short name): fedfsNfsTransFlagRdma 2421 Usage: attribute type 2423 Object Identifier: 1.3.6.1.4.1.31103.1.108 2424 Descriptor (short name): fedfsNfsClassSimul 2425 Usage: attribute type 2427 Object Identifier: 1.3.6.1.4.1.31103.1.109 2428 Descriptor (short name): fedfsNfsClassHandle 2429 Usage: attribute type 2431 Object Identifier: 1.3.6.1.4.1.31103.1.110 2432 Descriptor (short name): fedfsNfsClassFileid 2433 Usage: attribute type 2435 Object Identifier: 1.3.6.1.4.1.31103.1.111 2436 Descriptor (short name): fedfsNfsClassWritever 2437 Usage: attribute type 2439 Object Identifier: 1.3.6.1.4.1.31103.1.112 2440 Descriptor (short name): fedfsNfsClassChange 2441 Usage: attribute type 2443 Object Identifier: 1.3.6.1.4.1.31103.1.113 2444 Descriptor (short name): fedfsNfsClassReaddir 2445 Usage: attribute type 2447 Object Identifier: 1.3.6.1.4.1.31103.1.114 2448 Descriptor (short name): fedfsNfsReadRank 2449 Usage: attribute type 2450 Object Identifier: 1.3.6.1.4.1.31103.1.115 2451 Descriptor (short name): fedfsNfsReadOrder 2452 Usage: attribute type 2454 Object Identifier: 1.3.6.1.4.1.31103.1.116 2455 Descriptor (short name): fedfsNfsWriteRank 2456 Usage: attribute type 2458 Object Identifier: 1.3.6.1.4.1.31103.1.117 2459 Descriptor (short name): fedfsNfsWriteOrder 2460 Usage: attribute type 2462 Object Identifier: 1.3.6.1.4.1.31103.1.118 2463 Descriptor (short name): fedfsNfsVarSub 2464 Usage: attribute type 2466 Object Identifier: 1.3.6.1.4.1.31103.1.119 2467 Descriptor (short name): fedfsNfsValidFor 2468 Usage: attribute type 2470 Object Identifier: 1.3.6.1.4.1.31103.1.120 2471 Descriptor (short name): fedfsNfsURI 2472 Usage: attribute type 2474 Object Identifier: 1.3.6.1.4.1.31103.1.1001 2475 Descriptor (short name): fedfsNsdbContainerInfo 2476 Usage: object class 2478 Object Identifier: 1.3.6.1.4.1.31103.1.1002 2479 Descriptor (short name): fedfsFsn 2480 Usage: object class 2482 Object Identifier: 1.3.6.1.4.1.31103.1.1003 2483 Descriptor (short name): fedfsFsl 2484 Usage: object class 2486 Object Identifier: 1.3.6.1.4.1.31103.1.1004 2487 Descriptor (short name): fedfsNfsFsl 2488 Usage: object class 2490 8. Glossary 2492 Administrator: A user with the necessary authority to initiate 2493 administrative tasks on one or more servers. 2495 Admin Entity: A server or agent that administers a collection of 2496 fileservers and persistently stores the namespace information. 2498 File-access Client: Standard off-the-shelf network attached storage 2499 (NAS) client software that communicates with fileservers using a 2500 standard file-access protocol. 2502 Federation: A set of fileserver collections and singleton 2503 fileservers that use a common set of interfaces and protocols in 2504 order to provide to file-access clients a federated namespace 2505 accessible through a filesystem access protocol. 2507 Fileserver: A server that stores physical fileset data, or refers 2508 file-access clients to other fileservers. A fileserver provides 2509 access to its shared filesystem data via a file-access protocol. 2511 Fileset: The abstraction of a set of files and the directory tree 2512 that contains them. A fileset is the fundamental unit of data 2513 management in the federation. 2515 Note that all files within a fileset are descendants of one 2516 directory, and that filesets do not span filesystems. 2518 Filesystem: A self-contained unit of export for a fileserver, and 2519 the mechanism used to implement filesets. The fileset does not 2520 need to be rooted at the root of the filesystem, nor at the export 2521 point for the filesystem. 2523 A single filesystem MAY implement more than one fileset, if the 2524 file-access protocol and the fileserver permit this. 2526 File-access Protocol: A network filesystem access protocol such as 2527 NFSv3 [RFC1813], NFSv4 [3530bis], or CIFS (Common Internet File 2528 System) [MS-SMB] [MS-SMB2] [MS-CIFS]. 2530 FSL (Fileset Location): The location of the implementation of a 2531 fileset at a particular moment in time. An FSL MUST be something 2532 that can be translated into a protocol-specific description of a 2533 resource that a file-access client can access directly, such as an 2534 fs_locations attribute (for NFSv4), or a share name (for CIFS). 2536 FSN (Fileset Name): A platform-independent and globally unique name 2537 for a fileset. Two FSLs that implement replicas of the same 2538 fileset MUST have the same FSN, and if a fileset is migrated from 2539 one location to another, the FSN of that fileset MUST remain the 2540 same. 2542 Junction: A filesystem object used to link a directory name in the 2543 current fileset with an object within another fileset. The 2544 server-side "link" from a leaf node in one fileset to the root of 2545 another fileset. 2547 Namespace: A filename/directory tree that a sufficiently authorized 2548 file-access client can observe. 2550 NSDB (Namespace Database) Service: A service that maps FSNs to FSLs. 2551 The NSDB may also be used to store other information, such as 2552 annotations for these mappings and their components. 2554 NSDB Node: The name or location of a server that implements part of 2555 the NSDB service and is responsible for keeping track of the FSLs 2556 (and related info) that implement a given partition of the FSNs. 2558 Referral: A server response to a file-access client access that 2559 directs the client to evaluate the current object as a reference 2560 to an object at a different location (specified by an FSL) in 2561 another fileset, and possibly hosted on another fileserver. The 2562 client re-attempts the access to the object at the new location. 2564 Replica: A replica is a redundant implementation of a fileset. Each 2565 replica shares the same FSN, but has a different FSL. 2567 Replicas may be used to increase availability or performance. 2568 Updates to replicas of the same fileset MUST appear to occur in 2569 the same order, and therefore each replica is self-consistent at 2570 any moment. 2572 We do not assume that updates to each replica occur 2573 simultaneously. If a replica is offline or unreachable, the other 2574 replicas may be updated. 2576 Server Collection: A set of fileservers administered as a unit. A 2577 server collection may be administered with vendor-specific 2578 software. 2580 The namespace provided by a server collection could be part of the 2581 federated namespace. 2583 Singleton Server: A server collection containing only one server; a 2584 stand-alone fileserver. 2586 9. References 2587 9.1. Normative References 2589 [3530bis] Haynes, T. and D. Noveck, "NFS Version 4 Protocol", 2590 draft-ietf-nfsv4-rfc3530bis (Work In Progress), 2010. 2592 [RFC2079] Smith, M., "Definition of an X.500 Attribute Type and an 2593 Object Class to Hold Uniform Resource Identifiers (URIs)", 2594 RFC 2079, January 1997. 2596 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 2597 Requirement Levels", BCP 14, RFC 2119, March 1997. 2599 [RFC2203] Eisler, M., Chiu, A., and L. Ling, "RPCSEC_GSS Protocol 2600 Specification", RFC 2203, September 1997. 2602 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 2603 Schoenwaelder, Ed., "Structure of Management Information 2604 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 2606 [RFC2743] Linn, J., "Generic Security Service Application Program 2607 Interface Version 2, Update 1", RFC 2743, January 2000. 2609 [RFC2849] Good, G., "The LDAP Data Interchange Format (LDIF) - 2610 Technical Specification", RFC 2849, June 2000. 2612 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 2613 10646", STD 63, RFC 3629, November 2003. 2615 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 2616 Resource Identifier (URI): Generic Syntax", STD 66, 2617 RFC 3986, January 2005. 2619 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 2620 Unique IDentifier (UUID) URN Namespace", RFC 4122, 2621 July 2005. 2623 [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol 2624 (LDAP): Technical Specification Road Map", RFC 4510, 2625 June 2006. 2627 [RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol 2628 (LDAP): The Protocol", RFC 4511, June 2006. 2630 [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol 2631 (LDAP): Directory Information Models", RFC 4512, 2632 June 2006. 2634 [RFC4513] Harrison, R., "Lightweight Directory Access Protocol 2635 (LDAP): Authentication Methods and Security Mechanisms", 2636 RFC 4513, June 2006. 2638 [RFC4516] Smith, M. and T. Howes, "Lightweight Directory Access 2639 Protocol (LDAP): Uniform Resource Locator", RFC 4516, 2640 June 2006. 2642 [RFC4517] Legg, S., "Lightweight Directory Access Protocol (LDAP): 2643 Syntaxes and Matching Rules", RFC 4517, June 2006. 2645 [RFC4519] Sciberras, A., "Lightweight Directory Access Protocol 2646 (LDAP): Schema for User Applications", RFC 4519, 2647 June 2006. 2649 [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) 2650 Considerations for the Lightweight Directory Access 2651 Protocol (LDAP)", BCP 64, RFC 4520, June 2006. 2653 [RFC4530] Zeilenga, K., "Lightweight Directory Access Protocol 2654 (LDAP) entryUUID Operational Attribute", RFC 4530, 2655 June 2006. 2657 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 2658 IANA Considerations Section in RFCs", BCP 26, RFC 5226, 2659 May 2008. 2661 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 2662 Specifications: ABNF", STD 68, RFC 5234, January 2008. 2664 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 2665 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 2667 [RFC5661] Shepler, S., Eisler, M., and D. Noveck, "Network File 2668 System (NFS) Version 4 Minor Version 1 Protocol", 2669 RFC 5661, January 2010. 2671 9.2. Informative References 2673 [AFS] Howard, J., "An Overview of the Andrew File System", 2674 Proceeding of the USENIX Winter Technical Conference , 2675 1988. 2677 [FEDFS-ADMIN] 2678 Lentini, J., Everhart, C., Ellard, D., Tewari, R., and M. 2679 Naik, "Administration Protocol for Federated Filesystems", 2680 draft-ietf-nfsv4-federated-fs-admin (Work In Progress), 2681 2010. 2683 [MS-CIFS] Microsoft Corporation, "Common Internet File System (CIFS) 2684 Protocol Specification", MS-CIFS 2.0, November 2009. 2686 [MS-SMB] Microsoft Corporation, "Server Message Block (SMB) 2687 Protocol Specification", MS-SMB 17.0, November 2009. 2689 [MS-SMB2] Microsoft Corporation, "Server Message Block (SMB) Version 2690 2 Protocol Specification", MS-SMB2 19.0, November 2009. 2692 [RFC1813] Callaghan, B., Pawlowski, B., and P. Staubach, "NFS 2693 Version 3 Protocol Specification", RFC 1813, June 1995. 2695 [RFC2224] Callaghan, B., "NFS URL Scheme", RFC 2224, October 1997. 2697 [RFC3254] Alvestrand, H., "Definitions for talking about 2698 directories", RFC 3254, April 2002. 2700 [RFC5662] Shepler, S., Eisler, M., and D. Noveck, "Network File 2701 System (NFS) Version 4 Minor Version 1 External Data 2702 Representation Standard (XDR) Description", RFC 5662, 2703 January 2010. 2705 [RFC5716] Lentini, J., Everhart, C., Ellard, D., Tewari, R., and M. 2706 Naik, "Requirements for Federated File Systems", RFC 5716, 2707 January 2010. 2709 [RFC6641] Everhart, C., Adamson, W., and J. Zhang, "Using DNS SRV to 2710 Specify a Global File Namespace with NFS Version 4", 2711 RFC 6641, June 2012. 2713 Appendix A. Acknowledgments 2715 The authors and editor would like to thank Craig Everhart and Manoj 2716 Naik, who were co-authors of an earlier version of this document. In 2717 addition, we would like to thank Andy Adamson, Paul Lemahieu, Mario 2718 Wurzl, and Robert Thurlow for helping to author this document. 2720 We would like to thank George Amvrosiadis, Trond Myklebust, Howard 2721 Chu, and Nicolas Williams for their comments and review. 2723 The editor gratefully acknowledges the IESG reviewers, whose 2724 constructive comments helped make this a much stronger document. 2726 Finally, we would like to thank Andy Adamson, Rob Thurlow, and Tom 2727 Haynes for helping to get this document out the door. 2729 The extract.sh shell script and formatting conventions were first 2730 described by the authors of the NFSv4.1 XDR specification [RFC5662]. 2732 Authors' Addresses 2734 James Lentini 2735 NetApp 2736 1601 Trapelo Rd, Suite 16 2737 Waltham, MA 02451 2738 US 2740 Phone: +1 781-768-5359 2741 Email: jlentini@netapp.com 2743 Daniel Ellard 2744 Raytheon BBN Technologies 2745 10 Moulton Street 2746 Cambridge, MA 02138 2747 US 2749 Phone: +1 617-873-8004 2750 Email: dellard@bbn.com 2752 Renu Tewari 2753 IBM Almaden 2754 650 Harry Rd 2755 San Jose, CA 95120 2756 US 2758 Email: tewarir@us.ibm.com 2760 Charles Lever (editor) 2761 Oracle Corporation 2762 1015 Granger Avenue 2763 Ann Arbor, MI 48104 2764 US 2766 Phone: +1 248-614-5091 2767 Email: chuck.lever@oracle.com