idnits 2.17.1 draft-ietf-nfsv4-federated-fs-protocol-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) 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 lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 10, 2009) is 5375 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Downref: Normative reference to an Informational draft: draft-ietf-nfsv4-federated-fs-reqts (ref. 'FEDFS-REQTS') ** Obsolete normative reference: RFC 3530 (Obsoleted by RFC 7530) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 NFSv4 Working Group J. Lentini 3 Internet-Draft C. Everhart 4 Intended status: Standards Track NetApp 5 Expires: January 11, 2010 D. Ellard 6 BBN Technologies 7 R. Tewari 8 M. Naik 9 IBM Almaden 10 July 10, 2009 12 NSDB Protocol for Federated Filesystems 13 draft-ietf-nfsv4-federated-fs-protocol-02 15 Status of this Memo 17 This Internet-Draft is submitted to IETF in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as Internet- 23 Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt. 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 36 This Internet-Draft will expire on January 11, 2010. 38 Copyright Notice 40 Copyright (c) 2009 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents in effect on the date of 45 publication of this document (http://trustee.ietf.org/license-info). 46 Please review these documents carefully, as they describe your rights 47 and restrictions with respect to this document. 49 Abstract 51 This document describes a filesystem federation protocol that enables 52 file access and namespace traversal across collections of 53 independently administered fileservers. The protocol specifies a set 54 of interfaces by which fileservers with different administrators can 55 form a fileserver federation that provides a namespace composed of 56 the filesystems physically hosted on and exported by the constituent 57 fileservers. 59 Requirements Language 61 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 62 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 63 document are to be interpreted as described in [RFC2119]. 65 Table of Contents 67 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 68 2. Overview of Features and Concepts . . . . . . . . . . . . . . 4 69 2.1. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 5 70 2.2. Fileset and Fileset Name (FSN) . . . . . . . . . . . . . . 5 71 2.3. Fileset Location (FSL) . . . . . . . . . . . . . . . . . . 6 72 2.3.1. Mutual Consistency across Fileset Locations . . . . . 7 73 2.3.2. Caching of Fileset Locations . . . . . . . . . . . . . 8 74 2.4. Namespace Database (NSDB) . . . . . . . . . . . . . . . . 8 75 2.5. Mount Points, Junctions and Referrals . . . . . . . . . . 9 76 2.6. Unified Namespace and the Root Fileset . . . . . . . . . . 10 77 2.7. Fileservers . . . . . . . . . . . . . . . . . . . . . . . 10 78 2.8. File-access Clients . . . . . . . . . . . . . . . . . . . 10 79 3. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 80 3.1. Creating a Fileset and its FSL(s) . . . . . . . . . . . . 11 81 3.1.1. Creating a Fileset and an FSN . . . . . . . . . . . . 11 82 3.1.2. Adding a Replica of a Fileset . . . . . . . . . . . . 12 83 3.2. Junction Resolution . . . . . . . . . . . . . . . . . . . 12 84 3.3. Example Use Case for Fileset Annotations . . . . . . . . . 12 85 4. Mapping the NSDB onto LDAP . . . . . . . . . . . . . . . . . . 13 86 4.1. Basic LDAP Configuration . . . . . . . . . . . . . . . . . 13 87 4.2. LDAP Schema . . . . . . . . . . . . . . . . . . . . . . . 14 88 4.2.1. LDAP Attributes . . . . . . . . . . . . . . . . . . . 14 89 4.2.2. LDAP Objects . . . . . . . . . . . . . . . . . . . . . 21 90 5. NSDB Operations . . . . . . . . . . . . . . . . . . . . . . . 24 91 5.1. NSDB Operations for Administrators . . . . . . . . . . . . 24 92 5.1.1. Create an FSN . . . . . . . . . . . . . . . . . . . . 25 93 5.1.2. Delete an FSN . . . . . . . . . . . . . . . . . . . . 26 94 5.1.3. Create an FSL . . . . . . . . . . . . . . . . . . . . 26 95 5.1.4. Delete an FSL . . . . . . . . . . . . . . . . . . . . 27 96 5.1.5. Update an FSL . . . . . . . . . . . . . . . . . . . . 27 97 5.2. NSDB Operations for Fileservers . . . . . . . . . . . . . 28 98 5.2.1. Lookup FSLs for an FSN . . . . . . . . . . . . . . . . 28 99 6. Security Considerations . . . . . . . . . . . . . . . . . . . 29 100 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 101 7.1. LDAP Descriptor Registration . . . . . . . . . . . . . . . 30 102 8. Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 103 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 33 104 9.1. Normative References . . . . . . . . . . . . . . . . . . . 33 105 9.2. Informational References . . . . . . . . . . . . . . . . . 34 106 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 35 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 35 109 1. Introduction 111 A federated filesystem enables file access and namespace traversal in 112 a uniform, secure and consistent manner across multiple independent 113 fileservers within an enterprise or across multiple enterprises. 115 This document specifies a set of protocols that allow fileservers, 116 possibly from different vendors and with different administrators, to 117 cooperatively form a federation containing one or more federated 118 filesystems. Each federated filesystem's namespace is composed of 119 the filesystems physically hosted on and exported by the federation's 120 fileservers. A federation MAY contain a common namespace across all 121 its fileservers. A federation MAY project multiple namespaces and 122 enable clients to traverse each one. A federation MAY contain an 123 arbitrary number of namespace repositories, each belonging to a 124 different administrative entity, and each rendering a part of the 125 namespace. A federation MAY also have an arbitrary number of 126 administrative entities responsible for administering disjoint 127 subsets of the fileservers. 129 Traditionally, building a namespace that spans multiple fileservers 130 has been difficult for two reasons. First, the fileservers that 131 export pieces of the namespace are often not in the same 132 administrative domain. Second, there is no standard mechanism for 133 the fileservers to cooperatively present the namespace. Fileservers 134 may provide proprietary management tools and in some cases an 135 administrator may be able to use the proprietary tools to build a 136 shared namespace out of the exported filesystems. However, relying 137 on vendor-proprietary tools does not work in larger enterprises or 138 when collaborating across enterprises because the fileservers are 139 likely to be from multiple vendors or use different software 140 versions, each with their own namespace protocols, with no common 141 mechanism to manage the namespace or exchange namespace information. 143 The federated filesystem protocols in this document define how to 144 construct a namespace accessible by an NFSv4 [RFC3530] or NFSv4.1 145 [NFSv4.1] client and have been designed to accommodate other file 146 access protocols in the future. 148 The requirements for federated filesystems are described in 149 [FEDFS-REQTS]. A protocol for administering a fileserver's namespace 150 is described in [FEDFS-ADMIN]. In the rest of the document, the term 151 fileserver denotes a fileserver that is part of a federation. 153 2. Overview of Features and Concepts 154 2.1. Namespace 156 The goal of a unified namespace is to make all managed data available 157 to all clients via the same path in a common filesystem-like 158 namespace. This should be achieved with minimal or zero client 159 configuration. In particular, updates to the common namespace should 160 not require configuration changes at the client. Filesets, which are 161 the unit of data management, are a set of files and directories. 162 From the perspective of the clients, the common namespace is 163 constructed by mounting filesets that are physically located on 164 different fileservers. The namespace, which is defined in terms of 165 fileset definitions, fileset identifiers, the location of each 166 fileset in the namespace, and the physical location of the 167 implementation(s) of each fileset, is stored in a set of namespace 168 repositories, each managed by an administrative entity. The 169 namespace schema defines the model used for populating, modifying, 170 and querying the namespace repositories. It is not required by the 171 federation that the namespace be common across all fileservers. It 172 should be possible to have several independently rooted namespaces. 174 2.2. Fileset and Fileset Name (FSN) 176 A fileset is defined to be a container of data and is the basic unit 177 of data management. Depending on the implementation, they may be 178 anything between an individual directory of an exported filesystem to 179 an entire exported filesystem at a fileserver. A fileset is uniquely 180 represented by its fileset name (FSN). An FSN is considered unique 181 across the federation. An FSN contains information sufficient to 182 locate the namespace database (NSDB) that holds authoritative 183 information about it and an identifier, called the FsnUuid, that 184 identifies it on that NSDB. After an FSN is created, it is 185 associated with a fileset location (FSL) on a fileserver. A fileset 186 can be implemented by one or more FSLs. The attributes of an FSN 187 are: 189 NsdbName: the fully qualified domain name of an NSDB location 190 that contains authoritative information for this FSN. 192 FsnUuid: a 128-bit UUID (universally unique identifier), 193 conforming to [RFC4122], that is used to uniquely identify an 194 FSN. To minimize the probability of two UUIDs colliding, a 195 consistent procedure for generating UUIDs SHOULD be used 196 throughout the federation. Within the federation, UUIDs SHOULD 197 be generated using the procedure described for version 1 of the 198 UUID variant specified in [RFC4122]. An NSDB SHOULD ensure 199 that no two FSNs it stores have the same FsnUuid. 201 2.3. Fileset Location (FSL) 203 An FSL represents the location where the fileset data resides. Each 204 FSL contains the host addresses of the fileserver storing the FSL and 205 protocol specific information for accessing the FSL. Each location 206 has an associated type that determines the protocol(s) that may be 207 used to access its data. Type information can be used to decide the 208 list of locations that will be returned to the client. 210 Each FSL consists of: 212 FslUuid: a 128-bit UUID, conforming to [RFC4122], that is used to 213 uniquely identify an FSL. To minimize the probability of two 214 UUIDs colliding, a consistent procedure for generating UUIDs 215 SHOULD be used throughout the federation. Within the 216 federation, UUIDs SHOULD be generated using the procedure 217 described for version 1 of the UUID variant specified in 218 [RFC4122]. An NSDB SHOULD ensure that no two FSLs it stores 219 have the same FslUuid. 221 FsnUuid: the 128-bit UUID of the FSL's FSN. 223 NsdbName: the fully qualified domain name of an NSDB location 224 that contains authoritative information for this FSL. 226 FSL Host: the fully qualified domain name of the host fileserver 227 storing the physical data 229 FSL TTL: the time in seconds during which the FSL may be cached 231 Annotations: optional name/value pairs that can be interpreted by 232 a fileserver. The semantics of this field are not defined by 233 this document. These tuples are intended to be used by higher- 234 level protocols. 236 Descriptions: optional text descriptions. The semantics of this 237 field are not defined by this document. 239 In addition, an NFS FSL contains information suitable for an NFSv4 240 fs_locations [RFC3530] or NFSv4.1 fs_locations_info attribute 241 [NFSv4.1]: 243 Pathname: the exported pathname at that host fileserver 245 Major Version: the NFS protocol major version (e.g. 4 for 246 NFSv4.1) 248 Minor Version: the NFS protocol minor version (e.g. 1 for 249 NFSv4.1) 251 Currency: the time lag of this FSL represented as the number of 252 time units it lags the latest version as defined by the NFSv4.1 253 fs_locations_server's fls_currency field. A currency value of 254 0 represents the latest version. Currency values are less than 255 or equal to zero 257 Info: as defined by the NFSv4.1 fl_locations_server's fls_info 258 field. 260 Flags: as defined by the NFSv4.1 fs_locations_info's fli_flags 261 field. 263 Valid For: as defined by the NFSv4.1 fs_locations_info's 264 fli_valid_for field. 266 A fileset MAY be accessible by protocols other than NFS. For each 267 such protocol, a corresponding FSL subtype SHOULD be defined. The 268 contents and format of such FSL subtypes are not defined in this 269 document. 271 2.3.1. Mutual Consistency across Fileset Locations 273 All of the FSLs that have the same FSN (thereby reference the same 274 fileset) are equivalent from the point of view of client access; the 275 different locations of a fileset represent the same data, though 276 potentially at different points in time. Fileset locations are 277 equivalent but not identical. Locations may either be read-only or 278 read-write. Typically, multiple read-write locations are backed by a 279 clustered filesystem while read-only locations are replicas created 280 by a federation-initiated or external replication. Read-only 281 locations may represent consistent point-in-time copies of a read- 282 write location. The federation protocols, however, cannot prevent 283 subsequent changes to a read-only location nor guarantee point-in- 284 time consistency of a read-only location if the read-write location 285 is changing. 287 Regardless of the type, all locations exist at the same mount point 288 in the namespace and, thus, one client may be referred to one 289 location while another is directed to a different location. Since 290 updates to each fileset location are not controlled by the federation 291 protocol, it is the responsibility of administrators to guarantee the 292 functional equivalence of the data. 294 The federation protocol does not guarantee that the different 295 locations are mutually consistent in terms of the currency of the 296 data. It relies on the client file-access protocol (i.e., NFSv4) to 297 contain sufficient information to help the clients determine the 298 currency of the data at each location in order to ensure that the 299 clients do not revert back in time when switching locations. 301 2.3.2. Caching of Fileset Locations 303 To resolve an FSN to a set of FSL records, the fileserver queries the 304 appropriate NSDB for the FSL records. A fileserver MAY cache these 305 FSL records for a limited period of time. The period of time, if 306 any, during which FSL records are cached is indicated by the FSL's 307 TTL field. 309 The combination of FSL caching and FSL migration presents a 310 challenge. For example, suppose there are three fileservers named A, 311 B, and C and fileserver A contains a junction to fileset X stored on 312 fileserver B. Now suppose that fileset X is migrated from fileserver 313 B to fileserver C and the corresponding FSL information for fileset X 314 in the appropriate NSDB is updated. If fileserver A has a cached FSL 315 for fileset X, a user traversing the junction on fileserver A will be 316 referred to fileserver B even though fileset X has migrated to 317 fileserver C. If fileserver A was not caching FSL records, it would 318 have obtained the correct location of fileset X from the NSDB. 320 Administrators are advised to be aware of FSL caching when performing 321 a migration. When migrating a fileset, administrators SHOULD create 322 a junction at the fileset's old location referring back to the NSDB 323 entry for the fileset. This junction will redirect any users who 324 follow stale FSL information to the correct location. Thus, in the 325 above example, fileserver A would direct clients to fileserver B, but 326 fileserver B would in turn direct clients to fileserver C. 328 Such supplemental junctions (on fileserver B in the example) would 329 not be required to be in place forever. They need to stay in place 330 only until cached FSL entries for the target fileset are invalidated. 331 Each FSL contains a TTL field, a count in seconds of the time 332 interval which is an upper bound for the lifetime of the cached 333 information and a lower bound for the lifetime of the supplemental 334 junctions. For example, suppose this field contains the value 3600 335 seconds (one hour). In such a case, administrators MUST keep the 336 supplemental junctions in place for at least one hour after the 337 fileset move has taken place, and FSL data MUST NOT be cached by a 338 referring fileserver for more than one hour without a refresh. 340 2.4. Namespace Database (NSDB) 342 The NSDB service is a federation-wide service that provides 343 interfaces to define, update, and query FSN information and FSN to 344 FSL mapping information. An individual repository of namespace 345 information is called an NSDB location. Each NSDB location is 346 managed by a single administrative entity. A single admin entity can 347 manage multiple NSDB locations. 349 The difference between the NSDB service and an NSDB location is 350 analogous to that between the DNS service and a particular DNS 351 server. 353 Each NSDB location stores the definition of the FSNs for which it is 354 authoritative. It also stores the definitions of the FSLs associated 355 with those FSNs. An NSDB location is authoritative for the filesets 356 that it defines. An NSDB location can cache information from a peer 357 NSDB location. The fileserver can always contact a local NSDB 358 location (if it has been defined) or directly contact any NSDB 359 location to resolve a junction. Each NSDB location supports an LDAP 360 [RFC4510] interface and can be accessed by an LDAP client. 362 An NSDB MAY be replicated throughout the federation. If an NSDB is 363 replicated, the NSDB MUST exhibit loose, converging consistency as 364 defined in [RFC3254]. The mechanism by which this is achieved is 365 outside the scope of this document. Many LDAP implementations 366 support replication. These features MAY be used to replicate the 367 NSDB. 369 2.5. Mount Points, Junctions and Referrals 371 A mount point is a directory in a parent fileset where a target 372 fileset may be attached. If a client traverses the path leading from 373 the root of the namespace to the mount point of a target fileset it 374 should be able to access the data in that target fileset (assuming 375 appropriate permissions). 377 The directory where a fileset is mounted is represented by a junction 378 in the underlying filesystem. In other words, a junction can be 379 viewed as a reference from a directory in one fileset to the root of 380 the target fileset. A junction can be implemented as a special 381 marker on a directory that is interpreted by the fileserver as a 382 mount point, or by some other mechanism in the underlying filesystem. 384 What data is used by the underlying filesystem to represent the 385 junction is not defined by this protocol. The essential property is 386 that the server must be able to find, given the junction, the FSN for 387 the target fileset. The mechanism by which the server maps a 388 junction to an FSN is outside the scope of this document. The FSN 389 (as described earlier) contains both the the authoritative NSDB 390 location and the FsnUuid (a UUID for the fileset). 392 When a client traversal reaches a junction, the client is referred to 393 a list of FSLs associated with the FSN that was the target of the 394 junction. The client can then redirect its connection to one of the 395 FSLs. This act is called a referral. For NFSv4 and NFSv4.1 clients, 396 the FSL information is returned in the fs_locations and 397 fs_locations_info attributes respectively. 399 The federation protocols do not limit where and how many times a 400 fileset is mounted in the namespace. Filesets can be nested; a 401 fileset can be mounted under another fileset. 403 2.6. Unified Namespace and the Root Fileset 405 The root fileset, when defined, is the top-level fileset of the 406 federation-wide namespace. The root of the unified namespace is the 407 top level directory of this fileset. A set of designated fileservers 408 in the federation can export the root fileset to render the 409 federation-wide unified namespace. When a client mounts the root 410 fileset from any of these designated fileservers it can view a common 411 federation-wide namespace. The properties and schema definition of 412 the root fileset and the protocol details that describe how to 413 configure and replicate the root fileset are not defined in this 414 document. 416 2.7. Fileservers 418 Fileservers are servers that store the physical fileset data or refer 419 the client to other fileservers. A fileserver can be implemented in 420 a number of different ways, including a single system, a cluster of 421 systems, or some other configuration. A fileserver access to a 422 federated filesystem via NFSv4, NFSv4.1, or some other protocol. 424 2.8. File-access Clients 426 File access clients are standard off-the-shelf NAS clients that 427 access file data using the NFSv4 protocol, the NFSv4.1 protocol, or 428 some other protocol. 430 3. Examples 432 In this section we provide examples and discussion of the basic 433 operations facilitated by the federated filesystem protocol: creating 434 a fileset, adding a replica of a fileset, resolving a junction, and 435 creating a junction. 437 3.1. Creating a Fileset and its FSL(s) 439 A fileset is the abstraction of a set of files and their containing 440 directory tree. The fileset abstraction is the fundamental unit of 441 data management in the federation. This abstraction is implemented 442 by an actual directory tree whose root location is specified by a 443 fileset location (FSL). 445 In this section, we describe the basic requirements for starting with 446 a directory tree and creating a fileset that can be used in the 447 federation protocols. Note that we do not assume that the process of 448 creating a fileset requires any transformation of the files or the 449 directory hierarchy. The only thing that is required by this process 450 is assigning the fileset a fileset name (FSN) and expressing the 451 location(s) of the implementation of the fileset as FSL(s). 453 There are many possible variations to this procedure, depending on 454 how the FSN that binds the FSL is created, and whether other replicas 455 of the fileset exist, are known to the federation, and need to be 456 bound to the same FSN. 458 It is easiest to describe this in terms of how to create the initial 459 implementation of the fileset, and then describe how to add replicas. 461 3.1.1. Creating a Fileset and an FSN 463 1. Choose the NSDB node that will keep track of the FSL(s) and 464 related information for the fileset. 466 2. Request that the NSDB node register a new FSN for the fileset. 468 The FSN UUID is chosen by the administrator or generated 469 automatically by administration software. The former case is 470 used if the fileset is being restored, perhaps as part of 471 disaster recovery, and the administrator wishes to specify the 472 FSN UUID in order to permit existing junctions that reference 473 that FSN to work again. 475 At this point, the FSN exists, but its fileset locations are 476 unspecified. 478 3. Send the FSN, the hostname, the export path, the type, the 479 currency, info, and annotations for the fileset to the NSDB node. 481 The NSDB node records this info and creates the initial FSL for 482 the fileset. 484 3.1.2. Adding a Replica of a Fileset 486 Adding a replica is straightforward: the NSDB node and the FSN are 487 already known. The only remaining step is to add another FSL. 489 Note that the federation protocols do not include methods for 490 creating or managing replicas: this is assumed to be a platform- 491 dependent operation (at least at this time). The only interface 492 required is the ability to register or remove the registration of 493 replicas for a fileset. 495 3.2. Junction Resolution 497 A fileset may contain references to other filesets. These references 498 are represented by junctions. If a client requests access to a 499 fileset object that is a junction, the server resolves the junction 500 to discover the FSL(s) that implements the referenced fileset. 502 There are many possible variations to this procedure, depending on 503 how the junctions are represented and how the information necessary 504 to perform resolution is represented by the server. 506 Step 4 is the only step that interacts directly with the federation 507 protocols. The rest of the steps may use platform-specific 508 interfaces. 510 1. The server determines that the object being accessed is a 511 junction. 513 2. The server does a local lookup to find the FSN of the target 514 fileset. 516 3. Using the FSN, the server finds the NSDB node responsible for the 517 target object. 519 4. The server contacts that NSDB node and asks for the set of FSLs 520 that implement the target FSN. The NSDB node responds with a set 521 of FSLs. 523 3.3. Example Use Case for Fileset Annotations 525 The fileset annotations can be used to define relationships between 526 filesets that can be used by an auxiliary replication protocol. 527 Consider the scenario where a fileset is created and mounted at some 528 point in the namespace. A snapshot of the read-write FSL of that 529 fileset is taken periodically at different frequencies say a daily 530 snapshot or a weekly snapshot. The different snapshots are mounted 531 at different locations in the namespace. The daily snapshots are 532 considered as a different fileset from the weekly ones but both are 533 related to the source fileset. For this we can define an annotation 534 labeling the filesets as source and replica. The replication 535 protocol can use this information to copy data from one or more FSLs 536 of the source fileset to all the FSLs of the replica fileset. The 537 replica filesets are read-only while the source fileset is read- 538 write. 540 This follows the traditional Andrew File System (AFS) model of 541 mounting the read-only volume at a path in the namespace different 542 from that of the read-write volume [AFS]. 544 The federation protocol does not control or manage the relationship 545 among filesets. It merely enables annotating the filesets with user- 546 defined relationships. 548 4. Mapping the NSDB onto LDAP 550 This section describes how an NSDB is constructed using an LDAP 551 Version 3 [RFC4510] Directory. Section 4.1 describes the basic 552 properties of the LDAP configuration that MUST be used in order to 553 ensure compatibility between different implementations. Section 4.2 554 defines the new LDAP attribute types, the new object types, and 555 specifies how the distinguished name (DN) of each object instance 556 MUST be constructed. 558 4.1. Basic LDAP Configuration 560 The base name (or suffix) of the NSDB directory information tree 561 (DIT) is "o=fedfs". 563 The DN of the privileged LDAP user is, by convention, 564 "cn=admin,o=fedfs". This user is able to modify the contents of the 565 LDAP database. It is permitted to use a different DN (or add 566 additional privileged users) but if a different DN is used then every 567 admin entity that needs to modify the contents of the database or 568 view privileged information must be made aware of the new DN. 570 It MUST be possible for the anonymous (unauthenticated) user to 571 perform LDAP queries that access the NSDB data. 573 All implementations SHOULD use the same schema, or, at minimum, a 574 schema that includes all of the objects, with each of the attributes, 575 named in the following sections. 577 4.2. LDAP Schema 579 The schema definitions provided in this document use the LDAP schema 580 syntax defined in [RFC4512]. The definitions are formatted to allow 581 the reader to easily extract them from the document. The reader can 582 use the following shell script to extract the definitions: 584 586 #!/bin/sh 587 grep '^ *///' | sed 's?^ */// ??' | sed 's?^ *///$??' 589 591 If the above script is stored in a file called "extract.sh", and this 592 document is in a file called "spec.txt", then the reader can do: 594 596 sh extract.sh < spec.txt > fedfs.schema 598 600 The effect of the script is to remove leading white space from each 601 line, plus a sentinel sequence of "///". 603 4.2.1. LDAP Attributes 605 This section describes the required attributes of the NSDB LDAP 606 schema. 608 4.2.1.1. fedfsUuid 610 A fedfsUuid is the base type for all of the universally unique 611 identifiers (UUIDs) used by the federated filesystem protocols. 613 This SHOULD be defined in terms of the text representation of the 614 standard UUID (as defined in [RFC4122]). 616 It MAY also be useful, for purposes of debugging or annotation, to 617 permit a fedfsUuid to include members of a more general class of 618 strings. 620 A fedfsUuid is a single-valued LDAP attribute. It is formally 621 defined as follows: 623 /// 624 /// attributetype ( 625 /// 1.3.6.1.4.1.31103.1.1 NAME 'fedfsUuid' 626 /// DESC 'A UUID used by NSDB' 627 /// SUP name 628 /// SINGLE-VALUE 629 /// ) 630 /// 632 4.2.1.2. fedfsNetAddr 634 A fedfsNetAddr is the locative name of a network service. It MUST be 635 a UTF-8 string and represent a network location in either IPv4, IPv6, 636 or DNS host name notation. The format is the same as that specified 637 for an fs_location4's server array elements in section 11.9 of 638 [NFSv4.1]. 640 This attribute is single-valued. It is formally defined as follows: 642 /// 643 /// attributetype ( 644 /// 1.3.6.1.4.1.31103.1.2 NAME 'fedfsNetAddr' 645 /// DESC 'The network name of a host or service' 646 /// SUP name 647 /// SINGLE-VALUE 648 /// ) 649 /// 651 4.2.1.3. fsnUuid 653 A fsnUuid represents the fsnUuid component of an FSN. 655 The fsnUuid is a subclass of fedfsUuid. 657 This attribute is single-valued. 659 /// 660 /// attributetype ( 661 /// 1.3.6.1.4.1.31103.1.3 NAME 'fsnUuid' 662 /// DESC 'The FSN UUID component of an FSN' 663 /// SUP fedfsUuid 664 /// SINGLE-VALUE 665 /// ) 666 /// 668 4.2.1.4. nsdbName 670 An nsdbName is the NSDB component of an FSN. 672 The nsdbName attribute is a subclass of fedfsNetAddr. 674 This attribute is single-valued. 676 /// 677 /// attributetype ( 678 /// 1.3.6.1.4.1.31103.1.4 NAME 'nsdbName' 679 /// DESC 'The NSDB location component of an FSN' 680 /// SUP fedfsNetAddr 681 /// SINGLE-VALUE 682 /// ) 683 /// 685 4.2.1.5. fslUuid 687 Each FSL must have a UUID associated with it, which serves as part of 688 its DN. 690 The fslUuid attribute is a subclass of fedfsUuid. 692 This attribute is single-valued. 694 /// 695 /// attributetype ( 696 /// 1.3.6.1.4.1.31103.1.5 NAME 'fslUuid' 697 /// DESC 'UUID of an FSL' 698 /// SUP fedfsUuid 699 /// SINGLE-VALUE 700 /// ) 701 /// 703 4.2.1.6. fslHost 705 An fslHost is the hostname/port component of an FSL. 707 The fslHost attribute is a subclass of fedfsNetAddr. 709 This attribute is single-valued. 711 /// 712 /// attributetype ( 713 /// 1.3.6.1.4.1.31103.1.6 NAME 'fslHost' 714 /// DESC 'Service location for a fileserver' 715 /// SUP fedfsNetAddr 716 /// SINGLE-VALUE 717 /// ) 718 /// 720 4.2.1.7. fslTTL 722 An fslTTL is the amount of time in seconds an FSL SHOULD be cached by 723 a fileserver. The numeric fslTTL value should be converted to a 724 string and encoded as a UTF-8 string. 726 This attribute is single-valued. 728 /// 729 /// attributetype ( 730 /// 1.3.6.1.4.1.31103.1.7 NAME 'fslTTL' 731 /// DESC 'Time to live of an FSL' 732 /// SUP name 733 /// SINGLE-VALUE 734 /// ) 735 /// 737 4.2.1.8. fslNfsPath 739 The path component of an FSL encoded as a UTF-8 string. 741 This attribute is single-valued. 743 /// 744 /// attributetype ( 745 /// 1.3.6.1.4.1.31103.1.8 NAME 'fslNfsPath' 746 /// DESC 'Server-local path to a fileset' 747 /// SUP name 748 /// SINGLE-VALUE 749 /// ) 750 /// 752 4.2.1.9. fslNfsMajorVer 754 The NFS major version of the associated NFS FSL. The numeric fslTTL 755 value should be converted to a string and encoded as a UTF-8 string. 757 For example if the FSL was exported via NFS 4.1, the contents of this 758 attribute would be the value 4. 760 This attribute is single-valued. 762 /// 763 /// attributetype ( 764 /// 1.3.6.1.4.1.31103.1.9 NAME 'fslNfsMajorVer' 765 /// DESC 'NFS major version' 766 /// SUP name 767 /// SINGLE-VALUE 768 /// ) 769 /// 771 4.2.1.10. fslNfsMinorVer 773 The NFS minor version of the associated NFS FSL. The numeric fslTTL 774 value should be converted to a string and encoded as a UTF-8 string. 776 For example if the FSL was exported via NFS 4.1, the contents of this 777 attribute would be the value 1. 779 This attribute is single-valued. 781 /// 782 /// attributetype ( 783 /// 1.3.6.1.4.1.31103.1.10 NAME 'fslNfsMinorVer' 784 /// DESC 'NFS minor version' 785 /// SUP name 786 /// SINGLE-VALUE 787 /// ) 788 /// 790 4.2.1.11. fslNfsCurrency 792 The currency of an FSL. The signed 32-bit numeric value should be 793 converted to a string encoded as a UTF-8 string. 795 This attribute is used to populate the NFSv4.1 fs_locations_server's 796 currency field. 798 This attribute is single-valued. 800 /// 801 /// attributetype ( 802 /// 1.3.6.1.4.1.31103.1.11 NAME 'fslNfsCurrency' 803 /// DESC 'up-to-date measure of the data' 804 /// SUP name 805 /// SINGLE-VALUE 806 /// ) 807 /// 809 4.2.1.12. fslNfsInfo 811 Information about the FSL. The variable sized array of octets is 812 stored directly in this attribute. 814 This attribute is used to populate the NFSv4.1 fs_locations_server's 815 info field. 817 This attribute is single-valued. 819 /// 820 /// attributetype ( 821 /// 1.3.6.1.4.1.31103.1.12 NAME 'fslNfsInfo' 822 /// DESC 'Information about the FSL' 823 /// EQUALITY octetStringMatch 824 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 825 /// SINGLE-VALUE 826 /// ) 827 /// 829 1.3.6.1.4.1.1466.115.121.1.40 refers to the Octet String syntax 830 [RFC4517]. 832 4.2.1.13. fslNfsFlags 834 An NFS FSL's flags. The unsigned 32-bit numeric value should be 835 converted to a string encoded as a UTF-8 string. 837 This attribute is used to populate the NFSv4.1 fs_locations_info's 838 fli_flags field. 840 This attribute is single-valued. 842 /// 843 /// attributetype ( 844 /// 1.3.6.1.4.1.31103.1.13 NAME 'fslNfsFlags' 845 /// DESC 'Flags' 846 /// SUP name 847 /// SINGLE-VALUE 848 /// ) 849 /// 851 4.2.1.14. fslNfsValidFor 853 An NFS FSL's "valid for" flag. The signed 32-bit numeric value 854 should be converted to a string encoded as a UTF-8 string. 856 This attribute is used to populate the NFSv4.1 fs_locations_info's 857 fli_valid_for field. 859 This attribute is single-valued. 861 /// 862 /// attributetype ( 863 /// 1.3.6.1.4.1.31103.1.14 NAME 'fslNfsValidFor' 864 /// DESC 'Valid for time' 865 /// SUP name 866 /// SINGLE-VALUE 867 /// ) 868 /// 870 4.2.1.15. annotation 872 An annotation of an object. 874 This attribute is multi-valued; an object type that permits 875 annotations may have any number of annotations per instance. 877 /// 878 /// attributetype ( 879 /// 1.3.6.1.4.1.31103.1.15 NAME 'annotation' 880 /// DESC 'Annotation of an object' 881 /// SUP name 882 /// ) 883 /// 885 An annotation attribute MUST be an UTF-8 string formatted as follows: 887 "KEY" = "VAL" 889 White space, defined as space, form-feed ('\f'), newline ('\n'), 890 carriage return ('\r'), horizontal tab ('\t'), and vertical tab 891 ('\v') characters, is ignored. 893 KEY and VAL MAY may contain any UTF-8 characters. The following 894 escape sequences are allowed: 896 +-----------------+-------------+ 897 | escape sequence | replacement | 898 +-----------------+-------------+ 899 | \\ | \ | 900 | \" | " | 901 +-----------------+-------------+ 903 An annotation attribute that does not adhere to this format SHOULD be 904 ignored. 906 The following are examples of valid annotation attributes: 908 "key1" = "foo" 909 "another key" = "x=3" 910 "key-2" = "A string with \" and \\ characters." 912 which correspond to the following key/value pairs: 914 +-------------+-----------------------------------+ 915 | key | value | 916 +-------------+-----------------------------------+ 917 | key1 | foo | 918 | another key | x=3 | 919 | key-2 | A string with " and \ characters. | 920 +-------------+-----------------------------------+ 922 4.2.1.16. descr 924 This attribute is used to store an object's description encoded as a 925 UTF-8 string. 927 This attribute is multi-valued which permits any number of 928 descriptions per entry. 930 /// 931 /// attributetype ( 932 /// 1.3.6.1.4.1.31103.1.16 NAME 'descr' 933 /// DESC 'Description of an object' 934 /// SUP name 935 /// ) 936 /// 938 4.2.2. LDAP Objects 940 4.2.2.1. fedfsFsn 942 A fedfsFsn represents an FSN. 944 The required attributes of a fedfsFsn are an nsdbName and fsnUuid. 946 A fedfsFsn's annotation and descr attributes are OPTIONAL. 948 The DN of an FSN is REQUIRED to take the following form: 949 "fsnUuid=FSNUUID,o=fedfs", where FSNUUID is the UUID of the FSN. 950 Since LDAP requires a DN to be unique, this ensures that each FSN 951 entry has a unique UUID value within the LDAP directory. 953 A fedfsFsn MAY also have additional attributes, but these attributes 954 MUST NOT be referenced by any part of this document. 956 /// 957 /// objectclass ( 958 /// 1.3.6.1.4.1.31103.1.1001 NAME 'fedfsFsn' 959 /// DESC 'Represents a fileset' 960 /// SUP top STRUCTURAL 961 /// MUST ( 962 /// fsnUuid 963 /// $ nsdbName 964 /// ) 965 /// MAY ( 966 /// annotation 967 /// $ descr 968 /// )) 969 /// 971 4.2.2.2. fedfsFsl 973 The fedfsFsl object class represents an FSL. 975 A fedfsFsl's required attributes are an fslUuid, fsnUuid, nsdbName, 976 fslHost, and fslTTL. 978 A fedfsFsl's annotation and descr attributes are OPTIONAL. 980 The fedfsFsl is an abstract object class. Protocol specific subtypes 981 of this object class are used to store FSL information. The 982 fedfsNfsFsl object class defined below is used to record an NFS FSL's 983 location. Other subtypes MAY be defined for other protocols (e.g. 984 CIFS). 986 The DN of an FSL is REQUIRED to take the following form: 987 "fslUuid=FSLUUID,fsnUuid=FSNUUID,o=fedfs" where FSLUUID and FSNUUID 988 are the UUIDs of the FSL and its FSN respectively. Since LDAP 989 requires a DN to be unique, this ensures that each FSL entry has a 990 unique UUID value within the LDAP directory. 992 /// 993 /// objectclass ( 994 /// 1.3.6.1.4.1.31103.1.1002 NAME 'fedfsFsl' 995 /// DESC 'A physical location of a fileset' 996 /// SUP top ABSTRACT 997 /// MUST ( 998 /// fslUuid 999 /// $ fsnUuid 1000 /// $ nsdbName 1001 /// $ fslHost 1002 /// $ fslTTL 1003 /// ) 1004 /// MAY ( 1005 /// annotation 1006 /// $ descr 1007 /// )) 1008 /// 1010 4.2.2.3. fedfsNfsFsl 1012 A fedfsNfsFsl is used to represent an NFS FSL. The fedfsNfsFsl 1013 inherits all of the attributes of the fedfsFsl and extends the 1014 fedfsFsl with information specific to the NFS protocol. 1016 The DN of an NFS FSL is REQUIRED to take the following form: 1017 "fslUuid=FSLUUID,fsnUuid=FSNUUID,o=fedfs" where FSLUUID and FSNUUID 1018 are the UUIDs of the FSL and its FSN respectively. Since LDAP 1019 requires a DN to be unique, this ensures that each NFS FSL entry has 1020 a unique UUID value within the LDAP directory. 1022 /// 1023 /// objectclass ( 1024 /// 1.3.6.1.4.1.31103.1.1003 NAME 'fedfsNfsFsl' 1025 /// DESC 'A NFS location of a fileset' 1026 /// SUP fedfsFsl STRUCTURAL 1027 /// MUST ( 1028 /// fslNfsPath 1029 /// $ fslNfsMajorVer 1030 /// $ fslNfsMinorVer 1031 /// $ fslNfsCurrency 1032 /// $ fslNfsInfo 1033 /// $ fslNfsFlags 1034 /// $ fslNfsValidFor 1035 /// )) 1036 /// 1038 5. NSDB Operations 1040 The operations defined by the protocol can be described as several 1041 sub-protocols that are used by entities within the federation to 1042 perform different roles. 1044 The first of these sub-protocols defines how the state of an NSDB 1045 location can be initialized and updated. The primary use of this 1046 sub-protocol is by an administrator to add, edit, or delete filesets, 1047 their properties, and their fileset locations. 1049 The second of these sub-protocols defines the queries that are sent 1050 to an NSDB location in order to perform resolution (or to find other 1051 information about the data stored within that NSDB location) and the 1052 responses returned by the NSDB location. The primary use of this 1053 sub-protocol is by a fileserver in order to perform resolution, but 1054 it may also be used by an administrator to query the state of the 1055 system. 1057 The first and second sub-protocols are defined as LDAP operations, 1058 using the schema defined in the previous section. If each NSDB 1059 location is a standard LDAP server, then, in theory, it is 1060 unnecessary to describe the LDAP operations in detail, because the 1061 operations are ordinary LDAP operations to query and update records. 1062 However, we do not require that an NSDB location implement a complete 1063 LDAP service, and therefore we define in these sections the minimum 1064 level of LDAP functionality required to implement an NSDB location. 1066 The NSDB sub-protocols are defined in the next two sub-sections. 1068 The third sub-protocol defines the queries and other requests that 1069 are sent to a fileserver in order to get information from it or to 1070 modify the state of the fileserver in a manner related to the 1071 federation protocols. The primary purpose of this protocol is for an 1072 administrator to create or delete a junction or discover related 1073 information about a particular fileserver. 1075 The third sub-protocol is defined as an ONC RPC protocols. The 1076 reason for using ONC RPC instead of LDAP is that all fileservers 1077 support ONC RPC but some do not support an LDAP Directory server. 1079 The ONC RPC administration protocol is defined in [FEDFS-ADMIN]. 1081 5.1. NSDB Operations for Administrators 1083 The admin entity initiates and controls the commands to manage 1084 fileset and namespace information. The admin entity, however, is 1085 stateless. All state is maintained at the NSDB locations or at the 1086 fileserver. 1088 We require that each NSDB location be able to act as an LDAP server 1089 and that the protocol used for communicating between the admin entity 1090 and each NSDB location is LDAP. 1092 The names we assign to these operations are entirely for the purpose 1093 of exposition in this document, and are not part of the LDAP dialogs. 1095 In the description of the LDAP messages and LDIF, we use the 1096 following notation: constant strings and literal names are specified 1097 in lower or mixed case, while variables or values are specified in 1098 uppercase. 1100 5.1.1. Create an FSN 1102 The administrator uses this operation to create a new FSN by 1103 requesting the NSDB to create a new fedfsFsn in its LDAP database 1104 with an fsnUuid value of FSNUUID and an NsdbName value of NSDBNAME. 1106 The NSDB location that receives the request SHOULD check that the 1107 NSDBNAME matches its own value and return an error if it does not. 1108 This is to ensure that an FSN is always created by the NSDB location 1109 encoded within the FSN as its owner. 1111 The NSDB location that receives the request SHOULD check all of the 1112 attributes for validity and consistency, but this is not generally 1113 possible for LDAP servers because the consistency requirements cannot 1114 be expressed in the LDAP schema (although many LDAP servers can be 1115 extended, via plug-ins or other mechanisms, to add functionality 1116 beyond the strict definition of LDAP). 1118 5.1.1.1. LDAP Request 1120 The admin chooses the fsnUuid and NsdbName of the FSN. The fsnUuid 1121 is a UUID and should be chosen via a standard process for creating a 1122 UUID (described in [RFC4122]). The NsdbName is the name of the NSDB 1123 location that will serve as the source of definitive information 1124 about an FSN for the life of that FSN. In the example below, the 1125 admin server chooses a fsnUuid of FSNUUID and the NsdbName of 1126 NSDBNAME and then sends an LDAP ADD request, described by the LDIF 1127 below, to the NSDB location NSDBNAME. This will create a new 1128 fedfsFsn on that NSDB location with the given attributes in the LDAP 1129 database. 1131 dn: fsnUuid=FSNUUID,o=fedfs 1132 changeType: add 1133 objectClass: fedfsFsn 1134 fsnUuid: FSNUUID 1135 nsdbName: NSDBNAME 1137 5.1.2. Delete an FSN 1139 This operation deletes the given fileset name. If the FSN entry 1140 being deleted has child FSL entries, this function MUST return an 1141 error. This ensures that the NSDB will not contain any orphaned FSL 1142 entries. A compliant LDAP implementation will meet this requirement 1143 since Section 4.8 of [RFC4511] defines the LDAP delete operation to 1144 only be capable of removing leaf entries. 1146 Note that the FSN delete function only removes the fileset from the 1147 namespace (by removing the records for that FSN from the NSDB 1148 location that receives this request). The fileset and its data are 1149 not deleted. Any junction that has this FSN as its target may 1150 continue to point to this non-existent FSN. A dangling reference may 1151 be detected when a client tries to resolve the target of a junction 1152 that refers to the deleted FSN and the NSDB returns an error. 1154 5.1.2.1. LDAP Request 1156 The admin sends an LDAP DELETE request to the NSDB server to remove 1157 the fedfsFsn from the NSDB server. An example LDIF for the delete 1158 request is shown below. 1160 dn: fsnUuid=FSNUUID,o=fedfs 1161 changeType: delete 1163 5.1.3. Create an FSL 1165 This operations creates a new Fileset location at the given location 1166 denoted by HOST and PATH for the given FSN. Normally an FSL is 1167 identified by the HOST:PATH pair. A UUID is an optional way to 1168 identify an FSL if it is recovered to a different HOST:PATH after a 1169 backup/restore. 1171 The FSL create command will result in the admin server sending an 1172 LDAP ADD request to create a new fedfsFsl at the NSDB maintaining the 1173 given FSN. The example LDIF is shown below. The PATH is the 1174 pathname where the fileset is located on the fileserver HOST. 1176 5.1.3.1. LDAP Request 1178 The admin sends an LDAP ADD request to the NSDB server to add the 1179 FSL. An example LDIF for adding an NFS FSL is shown below. 1181 dn:fslUuid=UUID,fsnUuid=FSNUUID,o=fedfs 1182 changeType: add 1183 objectClass: fedfsNfsFsl 1184 fslUuid: UUID 1185 fsnUuid: FSNUUID 1186 nsdbName: NSDBNAME 1187 fslHost: HOST 1188 fslTTL: TTL 1189 fslNfsPath: PATH 1190 fslNfsMajorVer: MAJOR 1191 fslNfsMinorVer: MINOR 1192 fslNfsCurrency: CURRENCY 1193 fslNfsInfo: INFO 1194 fslNfsFlags: FLAGS 1195 fslNfsValidFor: TIME 1196 annotation: ANNOTATION 1197 descr: DESCR 1199 5.1.4. Delete an FSL 1201 This operation deletes the given Fileset location. The admin 1202 requests the NSDB location storing the fedfsFsl to delete it from its 1203 database. This operation does not result in the fileset location's 1204 data being deleted at the fileserver. 1206 5.1.4.1. LDAP Request 1208 The admin sends an LDAP DELETE request to the NSDB server to remove 1209 the FSL. 1211 dn: fslUuid=UUID,fsnUuid=FSNUUID,o=fedfs 1212 changeType: delete 1214 5.1.5. Update an FSL 1216 This operation updates the attributes of a given FSL. This command 1217 results in a change in the attributes of the fedfsFsl at the NSDB 1218 server maintaining this FSL. The attributes that must not change are 1219 the fslUuid and the fsnUuid of the fileset this FSL implements. 1221 5.1.5.1. LDAP Request 1223 The admin sends an LDAP MODIFY request to the NSDB server to update 1224 the FSL. 1226 dn: fslUuid=UUID,fsnUuid=FSNUUID,o=fedfs 1227 changeType: modify 1228 replace: ATTRIBUTE-TYPE 1230 5.2. NSDB Operations for Fileservers 1232 5.2.1. Lookup FSLs for an FSN 1234 Using an LDAP search, the fileserver can obtain all of the FSLs for a 1235 given FSN. The FSN's fsnUuid is used as the search key. To obtain a 1236 list of all FSLs, the following search can be used: 1238 LDAP Request 1239 Search base: fsnUuid=FSNUUID, o=fedfs 1240 Search scope: onelevel 1241 Search filter: (objectClass=fedfsFsl) 1243 This search is for the children of the object with DN 1244 "fsnUuid=FSNUUID,o=fedfs" with a filter for "objectClass = fedfsFsl". 1245 (If you want to be doubly careful, you can also filter by the 1246 nsdbName.) 1248 The following search can be used to obtain only the NFS FSLs: 1250 LDAP Request 1251 Search base: fsnUuid=FSNUUID, o=fedfs 1252 Search scope: onelevel 1253 Search filter: (objectClass=fedfsNfsFsl) 1255 This also searches for the children of the object with DN 1256 "fsnUuid=FSNUUID,o=fedfs", but the filter for "objectClass = 1257 fedfsNfsFsl" restricts the results to only NFS FSLs. (If you want to 1258 be doubly careful, you can also filter by the nsdbName.) 1260 The fileserver can present the search results in a format useful to 1261 the type of the client on whose behalf the fileserver is performing 1262 the request. For an NFS client, the fileserver can use the search 1263 results to construct an NFSv4 fs_locations list or NFSv4.1 1264 fs_locations_info list. 1266 6. Security Considerations 1268 Both LDAP and NFSv4/NFSv4.1 provide security mechanisms. When used 1269 in conjunction with the federated filesystem protocols described in 1270 this document, the use of these mechanisms is RECOMMENDED. 1271 Specifically, the use of RPCSEC_GSS [RFC2203] [RFC2743] is 1272 RECOMMENDED on all connections between a client and fileserver. For 1273 all LDAP connections established by the federated filesystem 1274 protocols, TLS [RFC5246] [RFC4513] is RECOMMENDED. 1276 Within a federation, there are two components that an attacker may be 1277 able to compromise: a fileserver and an NSDB. If an attacker 1278 compromises a fileserver, the attacker can interfere with the 1279 client's filesystem I/O operations (e.g. by returning fictitious data 1280 in the response to a read request) or fabricating a referral. The 1281 attacker's abilities are the same regardless of whether or not the 1282 federation protocols are in use. If an attacker compromises an NSDB, 1283 the attacker will be able to forge FSL information and thus poison 1284 the fileserver's referral information. Therefore an NSDB should be 1285 as secure as the fileservers which query it. 1287 It should be noted that the federation protocols do not directly 1288 provide access to filesystem data. The federation protocols only 1289 provide a mechanism for building a namespace. All data transfers 1290 occur between a client and server just as they would if the 1291 federation protocols were not in use. As a result, the federation 1292 protocols do not require new user authentication and authorization 1293 mechanisms or require a file server to act as a proxy for a client. 1295 7. IANA Considerations 1297 The LDAP attributes and object classes defined in this document are 1298 assigned object identifier (OID) values from the 1.3.6.1.4.1.31103.x 1299 range. This is an Internet Private Enterprise Numbers range and was 1300 assigned to the authors using the process described in [RFC2578]. 1302 In accordance with Section 3.4 and Section 4 of [RFC4520], the object 1303 identifier descriptors defined in this document (listed below) will 1304 be registered via the Expert Review process. 1306 7.1. LDAP Descriptor Registration 1308 Subject: Request for LDAP Descriptor Registration 1309 Person & email address to contact for further information: See 1310 "Author/Change Controller" 1311 Specification: draft-ietf-nfsv4-federated-fs-protocol 1312 Author/Change Controller: [document authors] 1314 Object Identifier: 1.3.6.1.4.1.31103.1.1 1315 Descriptor (short name): fedfsUuid 1317 Object Identifier: 1.3.6.1.4.1.31103.1.2 1318 Descriptor (short name): fedfsNetAddr 1320 Object Identifier: 1.3.6.1.4.1.31103.1.3 1321 Descriptor (short name): fsnUuid 1323 Object Identifier: 1.3.6.1.4.1.31103.1.4 1324 Descriptor (short name): nsdbName 1326 Object Identifier: 1.3.6.1.4.1.31103.1.5 1327 Descriptor (short name): fslUuid 1329 Object Identifier: 1.3.6.1.4.1.31103.1.6 1330 Descriptor (short name): fslHost 1332 Object Identifier: 1.3.6.1.4.1.31103.1.7 1333 Descriptor (short name): fslTTL 1335 Object Identifier: 1.3.6.1.4.1.31103.1.8 1336 Descriptor (short name): fslNfsPath 1338 Object Identifier: 1.3.6.1.4.1.31103.1.9 1339 Descriptor (short name): fslNfsMajorVer 1341 Object Identifier: 1.3.6.1.4.1.31103.1.10 1342 Descriptor (short name): fslNfsMinorVer 1344 Object Identifier: 1.3.6.1.4.1.31103.1.11 1345 Descriptor (short name): fslNfsCurrency 1347 Object Identifier: 1.3.6.1.4.1.31103.1.12 1348 Descriptor (short name): fslNfsInfo 1349 Object Identifier: 1.3.6.1.4.1.31103.1.13 1350 Descriptor (short name): fslNfsFlags 1352 Object Identifier: 1.3.6.1.4.1.31103.1.14 1353 Descriptor (short name): fslNfsValidFor 1355 Object Identifier: 1.3.6.1.4.1.31103.1.15 1356 Descriptor (short name): annotation 1358 Object Identifier: 1.3.6.1.4.1.31103.1.16 1359 Descriptor (short name): descr 1361 Object Identifier: 1.3.6.1.4.1.31103.1.1001 1362 Descriptor (short name): fedfsFsn 1364 Object Identifier: 1.3.6.1.4.1.31103.1.1002 1365 Descriptor (short name): fedfsFsl 1367 Object Identifier: 1.3.6.1.4.1.31103.1.1003 1368 Descriptor (short name): fedfsNfsFsl 1370 8. Glossary 1372 Administrator: user with the necessary authority to initiate 1373 administrative tasks on one or more servers. 1375 Admin entity: A server or agent that administers a collection of 1376 fileservers and persistently stores the namespace information. 1378 Client: Any client that accesses the fileserver data using a 1379 supported filesystem access protocol. 1381 Federation: A set of server collections and singleton servers that 1382 use a common set of interfaces and protocols in order to provide 1383 to their clients a federated namespace accessible through a 1384 filesystem access protocol. 1386 Fileserver: A server exporting a filesystem via a network filesystem 1387 access protocol. 1389 Fileset: The abstraction of a set of files and their containing 1390 directory tree. A fileset is the fundamental unit of data 1391 management in the federation. 1393 Note that all files within a fileset are descendants of one 1394 directory, and that filesets do not span filesystems. 1396 Filesystem: A self-contained unit of export for a fileserver, and 1397 the mechanism used to implement filesets. The fileset does not 1398 need to be rooted at the root of the filesystem, nor at the export 1399 point for the filesystem. 1401 A single filesystem MAY implement more than one fileset, if the 1402 client protocol and the fileserver permit this. 1404 Filesystem access protocol: A network filesystem access protocol 1405 such as NFSv2 [RFC1094], NFSv3 [RFC1813], NFSv4 [RFC3530], or 1406 CIFS. 1408 FSL (Fileset location): The location of the implementation of a 1409 fileset at a particular moment in time. A FSL MUST be something 1410 that can be translated into a protocol-specific description of a 1411 resource that a client can access directly, such as a fs_location 1412 (for NFSv4), or share name (for CIFS). Note that not all FSLs 1413 need to be explicitly exported as long as they are contained 1414 within an exported path on the fileserver. 1416 FSN (Fileset name): A platform-independent and globally unique name 1417 for a fileset. Two FSLs that implement replicas of the same 1418 fileset MUST have the same FSN, and if a fileset is migrated from 1419 one location to another, the FSN of that fileset MUST remain the 1420 same. 1422 Junction: A filesystem object used to link a directory name in the 1423 current fileset with an object within another fileset. The 1424 server-side "link" from a leaf node in one fileset to the root of 1425 another fileset. 1427 Namespace: A filename/directory tree that a sufficiently-authorized 1428 client can observe. 1430 NSDB (Namespace Database Service): A service that maps FSNs to FSLs. 1431 The NSDB may also be used to store other information, such as 1432 annotations for these mappings and their components. 1434 NSDB Node: The name or location of a server that implements part of 1435 the NSDB service and is responsible for keeping track of the FSLs 1436 (and related info) that implement a given partition of the FSNs. 1438 Referral: A server response to a client access that directs the 1439 client to evaluate the current object as a reference to an object 1440 at a different location (specified by an FSL) in another fileset, 1441 and possibly hosted on another fileserver. The client re-attempts 1442 the access to the object at the new location. 1444 Replica: A replica is a redundant implementation of a fileset. Each 1445 replica shares the same FSN, but has a different FSL. 1447 Replicas may be used to increase availability or performance. 1448 Updates to replicas of the same fileset MUST appear to occur in 1449 the same order, and therefore each replica is self-consistent at 1450 any moment. 1452 We do not assume that updates to each replica occur simultaneously 1453 If a replica is offline or unreachable, the other replicas may be 1454 updated. 1456 Server Collection: A set of fileservers administered as a unit. A 1457 server collection may be administered with vendor-specific 1458 software. 1460 The namespace provided by a server collection could be part of the 1461 federated namespace. 1463 Singleton Server: A server collection containing only one server; a 1464 stand-alone fileserver. 1466 9. References 1468 9.1. Normative References 1470 [FEDFS-ADMIN] 1471 Lentini, J., Everhart, C., Ellard, D., Tewari, R., and M. 1472 Naik, "Administration Protocol for Federated Filesystems", 1473 draft-ietf-nfsv4-federated-fs-admin (Work In Progress), 1474 2008. 1476 [FEDFS-REQTS] 1477 Lentini, J., Everhart, C., Ellard, D., Tewari, R., and M. 1478 Naik, "Requirements for Federated File Systems", 1479 draft-ietf-nfsv4-federated-fs-reqts (Work In Progress), 1480 2008. 1482 [NFSv4.1] Shepler, S. and M. Eisler, "NFS Version 4 Minor Version 1483 1", draft-ietf-nfsv4-minorversion1 (Work In Progress), 1484 2008. 1486 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1487 Requirement Levels", BCP 14, RFC 2119, March 1997. 1489 [RFC2203] Eisler, M., Chiu, A., and L. Ling, "RPCSEC_GSS Protocol 1490 Specification", RFC 2203, September 1997. 1492 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1493 Schoenwaelder, Ed., "Structure of Management Information 1494 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 1496 [RFC2743] Linn, J., "Generic Security Service Application Program 1497 Interface Version 2, Update 1", RFC 2743, January 2000. 1499 [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 1500 Beame, C., Eisler, M., and D. Noveck, "Network File System 1501 (NFS) version 4 Protocol", RFC 3530, April 2003. 1503 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1504 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1505 July 2005. 1507 [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol 1508 (LDAP): Technical Specification Road Map", RFC 4510, 1509 June 2006. 1511 [RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol 1512 (LDAP): The Protocol", RFC 4511, June 2006. 1514 [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol 1515 (LDAP): Directory Information Models", RFC 4512, 1516 June 2006. 1518 [RFC4513] Harrison, R., "Lightweight Directory Access Protocol 1519 (LDAP): Authentication Methods and Security Mechanisms", 1520 RFC 4513, June 2006. 1522 [RFC4517] Legg, S., "Lightweight Directory Access Protocol (LDAP): 1523 Syntaxes and Matching Rules", RFC 4517, June 2006. 1525 [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) 1526 Considerations for the Lightweight Directory Access 1527 Protocol (LDAP)", BCP 64, RFC 4520, June 2006. 1529 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1530 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1532 9.2. Informational References 1534 [AFS] Howard, J., "An Overview of the Andrew File System", 1535 Proceeding of the USENIX Winter Technical Conference , 1536 1988. 1538 [RFC1094] Nowicki, B., "NFS: Network File System Protocol 1539 specification", RFC 1094, March 1989. 1541 [RFC1813] Callaghan, B., Pawlowski, B., and P. Staubach, "NFS 1542 Version 3 Protocol Specification", RFC 1813, June 1995. 1544 [RFC3254] Alvestrand, H., "Definitions for talking about 1545 directories", RFC 3254, April 2002. 1547 Appendix A. Acknowledgments 1549 We would like to thank Andy Adamson of NetApp, Paul Lemahieu of EMC, 1550 Robert Thurlow of Sun Microsystems, and Mario Wurzl of EMC for 1551 helping to author this document. 1553 We would also like to thank George Amvrosiadis for pointing out that 1554 several LDAP attributes were missing the SINGLE-VALUE keyword in a 1555 draft version of this document. 1557 Authors' Addresses 1559 James Lentini 1560 NetApp 1561 1601 Trapelo Rd, Suite 16 1562 Waltham, MA 02451 1563 US 1565 Phone: +1 781-768-5359 1566 Email: jlentini@netapp.com 1568 Craig Everhart 1569 NetApp 1570 7301 Kit Creek Rd 1571 Research Triangle Park, NC 27709 1572 US 1574 Phone: +1 919-476-5320 1575 Email: everhart@netapp.com 1576 Daniel Ellard 1577 BBN Technologies 1578 10 Moulton Street 1579 Cambridge, MA 02138 1580 US 1582 Phone: +1 617-873-8000 1583 Email: dellard@bbn.com 1585 Renu Tewari 1586 IBM Almaden 1587 650 Harry Rd 1588 San Jose, CA 95120 1589 US 1591 Email: tewarir@us.ibm.com 1593 Manoj Naik 1594 IBM Almaden 1595 650 Harry Rd 1596 San Jose, CA 95120 1597 US 1599 Email: manoj@almaden.ibm.com