idnits 2.17.1 draft-ietf-nfsv4-federated-fs-protocol-03.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 (August 20, 2009) is 5361 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: February 21, 2010 D. Ellard 6 BBN Technologies 7 R. Tewari 8 M. Naik 9 IBM Almaden 10 August 20, 2009 12 NSDB Protocol for Federated Filesystems 13 draft-ietf-nfsv4-federated-fs-protocol-03 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 February 21, 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 . . . . . . . . . . . . . . . . . . . . . 22 90 5. NSDB Operations . . . . . . . . . . . . . . . . . . . . . . . 24 91 5.1. NSDB Operations for Administrators . . . . . . . . . . . . 25 92 5.1.1. Create an FSN . . . . . . . . . . . . . . . . . . . . 25 93 5.1.2. Delete an FSN . . . . . . . . . . . . . . . . . . . . 26 94 5.1.3. Create an FSL . . . . . . . . . . . . . . . . . . . . 27 95 5.1.4. Delete an FSL . . . . . . . . . . . . . . . . . . . . 27 96 5.1.5. Update an FSL . . . . . . . . . . . . . . . . . . . . 28 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 . . . . . . . . . . . . . . . . . . . . . 30 101 7.1. LDAP Descriptor Registration . . . . . . . . . . . . . . . 30 102 8. Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 103 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 104 9.1. Normative References . . . . . . . . . . . . . . . . . . . 34 105 9.2. Informational References . . . . . . . . . . . . . . . . . 35 106 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 36 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 36 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 Given the above configuration guidelines, an NSDB SHOULD be 578 constructed using a dedicated LDAP directory. Separate LDAP 579 directories may be used for other purposes, such as storing user 580 account information. By using an LDAP directory dedicated to storing 581 NSDB records, there is no need to disturb the configuration of any 582 other LDAP directories that store information unrelated to an NSDB. 584 4.2. LDAP Schema 586 The schema definitions provided in this document use the LDAP schema 587 syntax defined in [RFC4512]. The definitions are formatted to allow 588 the reader to easily extract them from the document. The reader can 589 use the following shell script to extract the definitions: 591 593 #!/bin/sh 594 grep '^ *///' | sed 's?^ */// ??' | sed 's?^ *///$??' 596 598 If the above script is stored in a file called "extract.sh", and this 599 document is in a file called "spec.txt", then the reader can do: 601 603 sh extract.sh < spec.txt > fedfs.schema 605 607 The effect of the script is to remove leading white space from each 608 line, plus a sentinel sequence of "///". 610 4.2.1. LDAP Attributes 612 This section describes the required attributes of the NSDB LDAP 613 schema. 615 4.2.1.1. fedfsUuid 617 A fedfsUuid is the base type for all of the universally unique 618 identifiers (UUIDs) used by the federated filesystem protocols. 620 This SHOULD be defined in terms of the text representation of the 621 standard UUID (as defined in [RFC4122]). 623 It MAY also be useful, for purposes of debugging or annotation, to 624 permit a fedfsUuid to include members of a more general class of 625 strings. 627 A fedfsUuid is a single-valued LDAP attribute. It is formally 628 defined as follows: 630 /// 631 /// attributetype ( 632 /// 1.3.6.1.4.1.31103.1.1 NAME 'fedfsUuid' 633 /// DESC 'A UUID used by NSDB' 634 /// SUP name 635 /// SINGLE-VALUE 636 /// ) 637 /// 639 4.2.1.2. fedfsNetAddr 641 A fedfsNetAddr is the locative name of a network service. It MUST be 642 a UTF-8 string and represent a network location in either IPv4, IPv6, 643 or DNS host name notation. The format is the same as that specified 644 for an fs_location4's server array elements in section 11.9 of 645 [NFSv4.1]. 647 This attribute is single-valued. It is formally defined as follows: 649 /// 650 /// attributetype ( 651 /// 1.3.6.1.4.1.31103.1.2 NAME 'fedfsNetAddr' 652 /// DESC 'The network name of a host or service' 653 /// SUP name 654 /// SINGLE-VALUE 655 /// ) 656 /// 658 4.2.1.3. fedfsFsnUuid 660 A fedfsFsnUuid represents the fedfsFsnUuid component of an FSN. 662 The fedfsFsnUuid is a subclass of fedfsUuid. 664 This attribute is single-valued. 666 /// 667 /// attributetype ( 668 /// 1.3.6.1.4.1.31103.1.3 NAME 'fedfsFsnUuid' 669 /// DESC 'The FSN UUID component of an FSN' 670 /// SUP fedfsUuid 671 /// SINGLE-VALUE 672 /// ) 673 /// 675 4.2.1.4. fedfsNsdbName 677 An fedfsNsdbName is the NSDB component of an FSN. 679 The fedfsNsdbName attribute is a subclass of fedfsNetAddr. 681 This attribute is single-valued. 683 /// 684 /// attributetype ( 685 /// 1.3.6.1.4.1.31103.1.4 NAME 'fedfsNsdbName' 686 /// DESC 'The NSDB location component of an FSN' 687 /// SUP fedfsNetAddr 688 /// SINGLE-VALUE 689 /// ) 690 /// 692 4.2.1.5. fedfsFslUuid 694 Each FSL must have a UUID associated with it, which serves as part of 695 its DN. 697 The fedfsFslUuid attribute is a subclass of fedfsUuid. 699 This attribute is single-valued. 701 /// 702 /// attributetype ( 703 /// 1.3.6.1.4.1.31103.1.5 NAME 'fedfsFslUuid' 704 /// DESC 'UUID of an FSL' 705 /// SUP fedfsUuid 706 /// SINGLE-VALUE 707 /// ) 708 /// 710 4.2.1.6. fedfsFslHost 712 An fedfsFslHost is the hostname/port component of an FSL. 714 The fedfsFslHost attribute is a subclass of fedfsNetAddr. 716 This attribute is single-valued. 718 /// 719 /// attributetype ( 720 /// 1.3.6.1.4.1.31103.1.6 NAME 'fedfsFslHost' 721 /// DESC 'Service location for a fileserver' 722 /// SUP fedfsNetAddr 723 /// SINGLE-VALUE 724 /// ) 725 /// 727 4.2.1.7. fedfsFslTTL 729 An fedfsFslTTL is the amount of time in seconds an FSL SHOULD be 730 cached by a fileserver. The numeric fedfsFslTTL value should be 731 converted to a string and encoded as a UTF-8 string. 733 This attribute is single-valued. 735 /// 736 /// attributetype ( 737 /// 1.3.6.1.4.1.31103.1.7 NAME 'fedfsFslTTL' 738 /// DESC 'Time to live of an FSL' 739 /// SUP name 740 /// SINGLE-VALUE 741 /// ) 742 /// 744 4.2.1.8. fedfsNfsPath 746 The path component of an FSL encoded as a UTF-8 string. 748 This attribute is single-valued. 750 /// 751 /// attributetype ( 752 /// 1.3.6.1.4.1.31103.1.8 NAME 'fedfsNfsPath' 753 /// DESC 'Server-local path to a fileset' 754 /// SUP name 755 /// SINGLE-VALUE 756 /// ) 757 /// 759 4.2.1.9. fedfsNfsMajorVer 761 The NFS major version of the associated NFS FSL. The numeric 762 fedfsNfsMajorVer value should be converted to a string and encoded as 763 a UTF-8 string. 765 For example if the FSL was exported via NFS 4.1, the contents of this 766 attribute would be the value 4. 768 This attribute is single-valued. 770 /// 771 /// attributetype ( 772 /// 1.3.6.1.4.1.31103.1.9 NAME 'fedfsNfsMajorVer' 773 /// DESC 'NFS major version' 774 /// SUP name 775 /// SINGLE-VALUE 776 /// ) 777 /// 779 4.2.1.10. fedfsNfsMinorVer 781 The NFS minor version of the associated NFS FSL. The numeric 782 fedfsNfsMinorVer value should be converted to a string and encoded as 783 a UTF-8 string. 785 For example if the FSL was exported via NFS 4.1, the contents of this 786 attribute would be the value 1. 788 This attribute is single-valued. 790 /// 791 /// attributetype ( 792 /// 1.3.6.1.4.1.31103.1.10 NAME 'fedfsNfsMinorVer' 793 /// DESC 'NFS minor version' 794 /// SUP name 795 /// SINGLE-VALUE 796 /// ) 797 /// 799 4.2.1.11. fedfsNfsCurrency 801 The currency of an FSL. The signed 32-bit numeric value should be 802 converted to a string encoded as a UTF-8 string. 804 This attribute is used to populate the NFSv4.1 fs_locations_server's 805 currency field. 807 This attribute is single-valued. 809 /// 810 /// attributetype ( 811 /// 1.3.6.1.4.1.31103.1.11 NAME 'fedfsNfsCurrency' 812 /// DESC 'up-to-date measure of the data' 813 /// SUP name 814 /// SINGLE-VALUE 815 /// ) 816 /// 818 4.2.1.12. fedfsNfsInfo 820 Information about the FSL. The variable sized array of octets is 821 stored directly in this attribute. 823 This attribute is used to populate the NFSv4.1 fs_locations_server's 824 info field. 826 This attribute is single-valued. 828 /// 829 /// attributetype ( 830 /// 1.3.6.1.4.1.31103.1.12 NAME 'fedfsNfsInfo' 831 /// DESC 'Information about the FSL' 832 /// EQUALITY octetStringMatch 833 /// SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 834 /// SINGLE-VALUE 835 /// ) 836 /// 838 1.3.6.1.4.1.1466.115.121.1.40 refers to the Octet String syntax 839 [RFC4517]. 841 4.2.1.13. fedfsNfsFlags 843 An NFS FSL's flags. The unsigned 32-bit numeric value should be 844 converted to a string encoded as a UTF-8 string. 846 This attribute is used to populate the NFSv4.1 fs_locations_info's 847 fli_flags field. 849 This attribute is single-valued. 851 /// 852 /// attributetype ( 853 /// 1.3.6.1.4.1.31103.1.13 NAME 'fedfsNfsFlags' 854 /// DESC 'Flags' 855 /// SUP name 856 /// SINGLE-VALUE 857 /// ) 858 /// 860 4.2.1.14. fedfsNfsValidFor 862 An NFS FSL's "valid for" flag. The signed 32-bit numeric value 863 should be converted to a string encoded as a UTF-8 string. 865 This attribute is used to populate the NFSv4.1 fs_locations_info's 866 fli_valid_for field. 868 This attribute is single-valued. 870 /// 871 /// attributetype ( 872 /// 1.3.6.1.4.1.31103.1.14 NAME 'fedfsNfsValidFor' 873 /// DESC 'Valid for time' 874 /// SUP name 875 /// SINGLE-VALUE 876 /// ) 877 /// 879 4.2.1.15. fedfsAnnotation 881 An annotation of an object. 883 This attribute is multi-valued; an object type that permits 884 annotations may have any number of annotations per instance. 886 /// 887 /// attributetype ( 888 /// 1.3.6.1.4.1.31103.1.15 NAME 'fedfsAnnotation' 889 /// DESC 'Annotation of an object' 890 /// SUP name 891 /// ) 892 /// 894 A fedfsAnnotation attribute MUST be an UTF-8 string formatted as 895 follows: 897 "KEY" = "VAL" 898 White space, defined as space, form-feed ('\f'), newline ('\n'), 899 carriage return ('\r'), horizontal tab ('\t'), and vertical tab 900 ('\v') characters, is ignored. 902 KEY and VAL MAY may contain any UTF-8 characters. The following 903 escape sequences are allowed: 905 +-----------------+-------------+ 906 | escape sequence | replacement | 907 +-----------------+-------------+ 908 | \\ | \ | 909 | \" | " | 910 +-----------------+-------------+ 912 A fedfsAnnotation attribute that does not adhere to this format 913 SHOULD be ignored. 915 The following are examples of valid fedfsAnnotation attributes: 917 "key1" = "foo" 918 "another key" = "x=3" 919 "key-2" = "A string with \" and \\ characters." 921 which correspond to the following key/value pairs: 923 +-------------+-----------------------------------+ 924 | key | value | 925 +-------------+-----------------------------------+ 926 | key1 | foo | 927 | another key | x=3 | 928 | key-2 | A string with " and \ characters. | 929 +-------------+-----------------------------------+ 931 4.2.1.16. fedfsDescr 933 This attribute is used to store an object's description encoded as a 934 UTF-8 string. 936 This attribute is multi-valued which permits any number of 937 descriptions per entry. 939 /// 940 /// attributetype ( 941 /// 1.3.6.1.4.1.31103.1.16 NAME 'fedfsDescr' 942 /// DESC 'Description of an object' 943 /// SUP name 944 /// ) 945 /// 947 4.2.2. LDAP Objects 949 4.2.2.1. fedfsFsn 951 A fedfsFsn represents an FSN. 953 The required attributes of a fedfsFsn are an fedfsNsdbName and 954 fedfsFsnUuid. 956 A fedfsFsn's fedfsAnnotation and fedfsDescr attributes are OPTIONAL. 958 The DN of an FSN is REQUIRED to take the following form: 959 "fedfsFsnUuid=FSNUUID,o=fedfs", where FSNUUID is the UUID of the FSN. 960 Since LDAP requires a DN to be unique, this ensures that each FSN 961 entry has a unique UUID value within the LDAP directory. 963 A fedfsFsn MAY also have additional attributes, but these attributes 964 MUST NOT be referenced by any part of this document. 966 /// 967 /// objectclass ( 968 /// 1.3.6.1.4.1.31103.1.1001 NAME 'fedfsFsn' 969 /// DESC 'Represents a fileset' 970 /// SUP top STRUCTURAL 971 /// MUST ( 972 /// fedfsFsnUuid 973 /// $ fedfsNsdbName 974 /// ) 975 /// MAY ( 976 /// fedfsAnnotation 977 /// $ fedfsDescr 978 /// )) 979 /// 981 4.2.2.2. fedfsFsl 983 The fedfsFsl object class represents an FSL. 985 A fedfsFsl's required attributes are an fedfsFslUuid, fedfsFsnUuid, 986 fedfsNsdbName, fedfsFslHost, and fedfsFslTTL. 988 A fedfsFsl's fedfsAnnotation and fedfsDescr attributes are OPTIONAL. 990 The fedfsFsl is an abstract object class. Protocol specific subtypes 991 of this object class are used to store FSL information. The 992 fedfsNfsFsl object class defined below is used to record an NFS FSL's 993 location. Other subtypes MAY be defined for other protocols (e.g. 994 CIFS). 996 The DN of an FSL is REQUIRED to take the following form: 997 "fedfsFslUuid=FSLUUID,fedfsFsnUuid=FSNUUID,o=fedfs" where FSLUUID and 998 FSNUUID are the UUIDs of the FSL and its FSN respectively. Since 999 LDAP requires a DN to be unique, this ensures that each FSL entry has 1000 a unique UUID value within the LDAP directory. 1002 /// 1003 /// objectclass ( 1004 /// 1.3.6.1.4.1.31103.1.1002 NAME 'fedfsFsl' 1005 /// DESC 'A physical location of a fileset' 1006 /// SUP top ABSTRACT 1007 /// MUST ( 1008 /// fedfsFslUuid 1009 /// $ fedfsFsnUuid 1010 /// $ fedfsNsdbName 1011 /// $ fedfsFslHost 1012 /// $ fedfsFslTTL 1013 /// ) 1014 /// MAY ( 1015 /// fedfsAnnotation 1016 /// $ fedfsDescr 1017 /// )) 1018 /// 1020 4.2.2.3. fedfsNfsFsl 1022 A fedfsNfsFsl is used to represent an NFS FSL. The fedfsNfsFsl 1023 inherits all of the attributes of the fedfsFsl and extends the 1024 fedfsFsl with information specific to the NFS protocol. 1026 The DN of an NFS FSL is REQUIRED to take the following form: 1027 "fedfsFslUuid=FSLUUID,fedfsFsnUuid=FSNUUID,o=fedfs" where FSLUUID and 1028 FSNUUID are the UUIDs of the FSL and its FSN respectively. Since 1029 LDAP requires a DN to be unique, this ensures that each NFS FSL entry 1030 has a unique UUID value within the LDAP directory. 1032 /// 1033 /// objectclass ( 1034 /// 1.3.6.1.4.1.31103.1.1003 NAME 'fedfsNfsFsl' 1035 /// DESC 'A NFS location of a fileset' 1036 /// SUP fedfsFsl STRUCTURAL 1037 /// MUST ( 1038 /// fedfsNfsPath 1039 /// $ fedfsNfsMajorVer 1040 /// $ fedfsNfsMinorVer 1041 /// $ fedfsNfsCurrency 1042 /// $ fedfsNfsInfo 1043 /// $ fedfsNfsFlags 1044 /// $ fedfsNfsValidFor 1045 /// )) 1046 /// 1048 5. NSDB Operations 1050 The operations defined by the protocol can be described as several 1051 sub-protocols that are used by entities within the federation to 1052 perform different roles. 1054 The first of these sub-protocols defines how the state of an NSDB 1055 location can be initialized and updated. The primary use of this 1056 sub-protocol is by an administrator to add, edit, or delete filesets, 1057 their properties, and their fileset locations. 1059 The second of these sub-protocols defines the queries that are sent 1060 to an NSDB location in order to perform resolution (or to find other 1061 information about the data stored within that NSDB location) and the 1062 responses returned by the NSDB location. The primary use of this 1063 sub-protocol is by a fileserver in order to perform resolution, but 1064 it may also be used by an administrator to query the state of the 1065 system. 1067 The first and second sub-protocols are defined as LDAP operations, 1068 using the schema defined in the previous section. If each NSDB 1069 location is a standard LDAP server, then, in theory, it is 1070 unnecessary to describe the LDAP operations in detail, because the 1071 operations are ordinary LDAP operations to query and update records. 1072 However, we do not require that an NSDB location implement a complete 1073 LDAP service, and therefore we define in these sections the minimum 1074 level of LDAP functionality required to implement an NSDB location. 1076 The NSDB sub-protocols are defined in the next two sub-sections. 1078 The third sub-protocol defines the queries and other requests that 1079 are sent to a fileserver in order to get information from it or to 1080 modify the state of the fileserver in a manner related to the 1081 federation protocols. The primary purpose of this protocol is for an 1082 administrator to create or delete a junction or discover related 1083 information about a particular fileserver. 1085 The third sub-protocol is defined as an ONC RPC protocols. The 1086 reason for using ONC RPC instead of LDAP is that all fileservers 1087 support ONC RPC but some do not support an LDAP Directory server. 1089 The ONC RPC administration protocol is defined in [FEDFS-ADMIN]. 1091 5.1. NSDB Operations for Administrators 1093 The admin entity initiates and controls the commands to manage 1094 fileset and namespace information. The admin entity, however, is 1095 stateless. All state is maintained at the NSDB locations or at the 1096 fileserver. 1098 We require that each NSDB location be able to act as an LDAP server 1099 and that the protocol used for communicating between the admin entity 1100 and each NSDB location is LDAP. 1102 The names we assign to these operations are entirely for the purpose 1103 of exposition in this document, and are not part of the LDAP dialogs. 1105 In the description of the LDAP messages and LDIF, we use the 1106 following notation: constant strings and literal names are specified 1107 in lower or mixed case, while variables or values are specified in 1108 uppercase. 1110 5.1.1. Create an FSN 1112 The administrator uses this operation to create a new FSN by 1113 requesting the NSDB to create a new fedfsFsn in its LDAP database 1114 with an fedfsFsnUuid value of FSNUUID and an NsdbName value of 1115 NSDBNAME. 1117 The NSDB location that receives the request SHOULD check that the 1118 NSDBNAME matches its own value and return an error if it does not. 1119 This is to ensure that an FSN is always created by the NSDB location 1120 encoded within the FSN as its owner. 1122 The NSDB location that receives the request SHOULD check all of the 1123 attributes for validity and consistency, but this is not generally 1124 possible for LDAP servers because the consistency requirements cannot 1125 be expressed in the LDAP schema (although many LDAP servers can be 1126 extended, via plug-ins or other mechanisms, to add functionality 1127 beyond the strict definition of LDAP). 1129 5.1.1.1. LDAP Request 1131 The admin chooses the fedfsFsnUuid and NsdbName of the FSN. The 1132 fedfsFsnUuid is a UUID and should be chosen via a standard process 1133 for creating a UUID (described in [RFC4122]). The NsdbName is the 1134 name of the NSDB location that will serve as the source of definitive 1135 information about an FSN for the life of that FSN. In the example 1136 below, the admin server chooses a fedfsFsnUuid of FSNUUID and the 1137 NsdbName of NSDBNAME and then sends an LDAP ADD request, described by 1138 the LDIF below, to the NSDB location NSDBNAME. This will create a 1139 new fedfsFsn on that NSDB location with the given attributes in the 1140 LDAP database. 1142 dn: fedfsFsnUuid=FSNUUID,o=fedfs 1143 changeType: add 1144 objectClass: fedfsFsn 1145 fedfsFsnUuid: FSNUUID 1146 fedfsNsdbName: NSDBNAME 1148 5.1.2. Delete an FSN 1150 This operation deletes the given fileset name. If the FSN entry 1151 being deleted has child FSL entries, this function MUST return an 1152 error. This ensures that the NSDB will not contain any orphaned FSL 1153 entries. A compliant LDAP implementation will meet this requirement 1154 since Section 4.8 of [RFC4511] defines the LDAP delete operation to 1155 only be capable of removing leaf entries. 1157 Note that the FSN delete function only removes the fileset from the 1158 namespace (by removing the records for that FSN from the NSDB 1159 location that receives this request). The fileset and its data are 1160 not deleted. Any junction that has this FSN as its target may 1161 continue to point to this non-existent FSN. A dangling reference may 1162 be detected when a client tries to resolve the target of a junction 1163 that refers to the deleted FSN and the NSDB returns an error. 1165 5.1.2.1. LDAP Request 1167 The admin sends an LDAP DELETE request to the NSDB server to remove 1168 the fedfsFsn from the NSDB server. An example LDIF for the delete 1169 request is shown below. 1171 dn: fedfsFsnUuid=FSNUUID,o=fedfs 1172 changeType: delete 1174 5.1.3. Create an FSL 1176 This operations creates a new Fileset location at the given location 1177 denoted by HOST and PATH for the given FSN. Normally an FSL is 1178 identified by the HOST:PATH pair. A UUID is an optional way to 1179 identify an FSL if it is recovered to a different HOST:PATH after a 1180 backup/restore. 1182 The FSL create command will result in the admin server sending an 1183 LDAP ADD request to create a new fedfsFsl at the NSDB maintaining the 1184 given FSN. The example LDIF is shown below. The PATH is the 1185 pathname where the fileset is located on the fileserver HOST. 1187 5.1.3.1. LDAP Request 1189 The admin sends an LDAP ADD request to the NSDB server to add the 1190 FSL. An example LDIF for adding an NFS FSL is shown below. 1192 dn:fedfsFslUuid=UUID,fedfsFsnUuid=FSNUUID,o=fedfs 1193 changeType: add 1194 objectClass: fedfsNfsFsl 1195 fedfsFslUuid: UUID 1196 fedfsFsnUuid: FSNUUID 1197 fedfsNsdbName: NSDBNAME 1198 fedfsFslHost: HOST 1199 fedfsFslTTL: TTL 1200 fedfsNfsPath: PATH 1201 fedfsNfsMajorVer: MAJOR 1202 fedfsNfsMinorVer: MINOR 1203 fedfsNfsCurrency: CURRENCY 1204 fedfsNfsInfo: INFO 1205 fedfsNfsFlags: FLAGS 1206 fedfsNfsValidFor: TIME 1207 fedfsAnnotation: ANNOTATION 1208 fedfsDescr: DESCR 1210 5.1.4. Delete an FSL 1212 This operation deletes the given Fileset location. The admin 1213 requests the NSDB location storing the fedfsFsl to delete it from its 1214 database. This operation does not result in the fileset location's 1215 data being deleted at the fileserver. 1217 5.1.4.1. LDAP Request 1219 The admin sends an LDAP DELETE request to the NSDB server to remove 1220 the FSL. 1222 dn: fedfsFslUuid=UUID,fedfsFsnUuid=FSNUUID,o=fedfs 1223 changeType: delete 1225 5.1.5. Update an FSL 1227 This operation updates the attributes of a given FSL. This command 1228 results in a change in the attributes of the fedfsFsl at the NSDB 1229 server maintaining this FSL. The attributes that must not change are 1230 the fedfsFslUuid and the fedfsFsnUuid of the fileset this FSL 1231 implements. 1233 5.1.5.1. LDAP Request 1235 The admin sends an LDAP MODIFY request to the NSDB server to update 1236 the FSL. 1238 dn: fedfsFslUuid=UUID,fedfsFsnUuid=FSNUUID,o=fedfs 1239 changeType: modify 1240 replace: ATTRIBUTE-TYPE 1242 5.2. NSDB Operations for Fileservers 1244 5.2.1. Lookup FSLs for an FSN 1246 Using an LDAP search, the fileserver can obtain all of the FSLs for a 1247 given FSN. The FSN's fedfsFsnUuid is used as the search key. The 1248 following examples use the LDAP URI format defined in [RFC4516]. 1250 To obtain a list of all FSLs on the NSDB named "nsdb.example.com", 1251 the following search can be used (for readability the URI is split 1252 into two lines): 1254 ldap://nsdb.example.com/fsnUuid=FSNUUID,o=fedfs??one? 1255 (objectClass=fedfsFsl) 1257 This search is for the children of the object with DN 1258 "fedfsFsnUuid=FSNUUID,o=fedfs" with a filter for 1259 "objectClass=fedfsFsl". The scope value of "one" restricts the 1260 search to the entry's children (rather than the entire subtree below 1261 the entry) and the filter ensures that only FSL entries are returned. 1263 The following search can be used to obtain only the NFS FSLs on the 1264 NSDB named "nsdb.example.com" (for readability the URI is split into 1265 two lines): 1267 ldap://nsdb.example.com/fsnUuid=FSNUUID,o=fedfs??one? 1268 (objectClass=fedfsNfsFsl) 1270 This also searches for the children of the object with DN 1271 "fedfsFsnUuid=FSNUUID,o=fedfs", but the filter for "objectClass = 1272 fedfsNfsFsl" restricts the results to only NFS FSLs. 1274 The fileserver can present the search results in a format useful to 1275 the type of the client on whose behalf the fileserver is performing 1276 the request. For an NFS client, the fileserver can use the search 1277 results to construct an NFSv4 fs_locations list or NFSv4.1 1278 fs_locations_info list. 1280 6. Security Considerations 1282 Both NFSv4/NFSv4.1 and LDAP provide security mechanisms. When used 1283 in conjunction with the federated filesystem protocols described in 1284 this document, the use of these mechanisms is RECOMMENDED. 1285 Specifically, the use of RPCSEC_GSS [RFC2203], which is built on the 1286 GSS-API [RFC2743], is RECOMMENDED on all NFS connections between a 1287 client and fileserver. The "Security Considerations" sections of the 1288 the NFSv4 [RFC3530] and NFSv4.1 [NFSv4.1] specifications contain 1289 special considerations for the handling of GETATTR operations for the 1290 fs_locations and fs_locations_info attributes. For all LDAP 1291 connections established by the federated filesystem protocols, the 1292 use of TLS [RFC5246], as described in [RFC4513], is RECOMMENDED. 1294 Within a federation, there are two types of components an attacker 1295 may compromise: a fileserver and an NSDB. 1297 If an attacker compromises a fileserver, the attacker can interfere 1298 with the client's filesystem I/O operations (e.g. by returning 1299 fictitious data in the response to a read request) or fabricating a 1300 referral. The attacker's abilities are the same regardless of 1301 whether or not the federation protocols are in use. While the 1302 federation protocols do not give the attacker additional 1303 capabilities, they are additional targets for attack. The LDAP 1304 protocol described in Section 5.2 SHOULD be secured using the methods 1305 described above to defeat attacks on a fileserver via this channel. 1307 If an attacker compromises an NSDB, the attacker will be able to 1308 forge FSL information and thus poison the fileserver's referral 1309 information. Therefore an NSDB should be as secure as the 1310 fileservers which query it. The LDAP protocol described in 1311 Section 5.1 SHOULD be secured using the methods described above to 1312 defeat attacks on an NSDB via this channel. 1314 It should be noted that the federation protocols do not directly 1315 provide access to filesystem data. The federation protocols only 1316 provide a mechanism for building a namespace. All data transfers 1317 occur between a client and server just as they would if the 1318 federation protocols were not in use. As a result, the federation 1319 protocols do not require new user authentication and authorization 1320 mechanisms or require a fileserver to act as a proxy for a client. 1322 7. IANA Considerations 1324 The LDAP attributes and object classes defined in this document are 1325 assigned object identifier (OID) values from the 1.3.6.1.4.1.31103.x 1326 range. This is an Internet Private Enterprise Numbers range and was 1327 assigned to the authors using the process described in [RFC2578]. 1329 In accordance with Section 3.4 and Section 4 of [RFC4520], the object 1330 identifier descriptors defined in this document (listed below) will 1331 be registered via the Expert Review process. 1333 7.1. LDAP Descriptor Registration 1335 Subject: Request for LDAP Descriptor Registration 1336 Person & email address to contact for further information: See 1337 "Author/Change Controller" 1338 Specification: draft-ietf-nfsv4-federated-fs-protocol 1339 Author/Change Controller: [document authors] 1341 Object Identifier: 1.3.6.1.4.1.31103.1.1 1342 Descriptor (short name): fedfsUuid 1344 Object Identifier: 1.3.6.1.4.1.31103.1.2 1345 Descriptor (short name): fedfsNetAddr 1346 Object Identifier: 1.3.6.1.4.1.31103.1.3 1347 Descriptor (short name): fedfsFsnUuid 1349 Object Identifier: 1.3.6.1.4.1.31103.1.4 1350 Descriptor (short name): fedfsNsdbName 1352 Object Identifier: 1.3.6.1.4.1.31103.1.5 1353 Descriptor (short name): fedfsFslUuid 1355 Object Identifier: 1.3.6.1.4.1.31103.1.6 1356 Descriptor (short name): fedfsFslHost 1358 Object Identifier: 1.3.6.1.4.1.31103.1.7 1359 Descriptor (short name): fedfsFslTTL 1361 Object Identifier: 1.3.6.1.4.1.31103.1.8 1362 Descriptor (short name): fedfsNfsPath 1364 Object Identifier: 1.3.6.1.4.1.31103.1.9 1365 Descriptor (short name): fedfsNfsMajorVer 1367 Object Identifier: 1.3.6.1.4.1.31103.1.10 1368 Descriptor (short name): fedfsNfsMinorVer 1370 Object Identifier: 1.3.6.1.4.1.31103.1.11 1371 Descriptor (short name): fedfsNfsCurrency 1373 Object Identifier: 1.3.6.1.4.1.31103.1.12 1374 Descriptor (short name): fedfsNfsInfo 1376 Object Identifier: 1.3.6.1.4.1.31103.1.13 1377 Descriptor (short name): fedfsNfsFlags 1379 Object Identifier: 1.3.6.1.4.1.31103.1.14 1380 Descriptor (short name): fedfsNfsValidFor 1382 Object Identifier: 1.3.6.1.4.1.31103.1.15 1383 Descriptor (short name): fedfsAnnotation 1385 Object Identifier: 1.3.6.1.4.1.31103.1.16 1386 Descriptor (short name): fedfsDescr 1388 Object Identifier: 1.3.6.1.4.1.31103.1.1001 1389 Descriptor (short name): fedfsFsn 1390 Object Identifier: 1.3.6.1.4.1.31103.1.1002 1391 Descriptor (short name): fedfsFsl 1393 Object Identifier: 1.3.6.1.4.1.31103.1.1003 1394 Descriptor (short name): fedfsNfsFsl 1396 8. Glossary 1398 Administrator: user with the necessary authority to initiate 1399 administrative tasks on one or more servers. 1401 Admin entity: A server or agent that administers a collection of 1402 fileservers and persistently stores the namespace information. 1404 Client: Any client that accesses the fileserver data using a 1405 supported filesystem access protocol. 1407 Federation: A set of server collections and singleton servers that 1408 use a common set of interfaces and protocols in order to provide 1409 to their clients a federated namespace accessible through a 1410 filesystem access protocol. 1412 Fileserver: A server exporting a filesystem via a network filesystem 1413 access protocol. 1415 Fileset: The abstraction of a set of files and their containing 1416 directory tree. A fileset is the fundamental unit of data 1417 management in the federation. 1419 Note that all files within a fileset are descendants of one 1420 directory, and that filesets do not span filesystems. 1422 Filesystem: A self-contained unit of export for a fileserver, and 1423 the mechanism used to implement filesets. The fileset does not 1424 need to be rooted at the root of the filesystem, nor at the export 1425 point for the filesystem. 1427 A single filesystem MAY implement more than one fileset, if the 1428 client protocol and the fileserver permit this. 1430 Filesystem access protocol: A network filesystem access protocol 1431 such as NFSv2 [RFC1094], NFSv3 [RFC1813], NFSv4 [RFC3530], or 1432 CIFS. 1434 FSL (Fileset location): The location of the implementation of a 1435 fileset at a particular moment in time. A FSL MUST be something 1436 that can be translated into a protocol-specific description of a 1437 resource that a client can access directly, such as a fs_location 1438 (for NFSv4), or share name (for CIFS). Note that not all FSLs 1439 need to be explicitly exported as long as they are contained 1440 within an exported path on the fileserver. 1442 FSN (Fileset name): A platform-independent and globally unique name 1443 for a fileset. Two FSLs that implement replicas of the same 1444 fileset MUST have the same FSN, and if a fileset is migrated from 1445 one location to another, the FSN of that fileset MUST remain the 1446 same. 1448 Junction: A filesystem object used to link a directory name in the 1449 current fileset with an object within another fileset. The 1450 server-side "link" from a leaf node in one fileset to the root of 1451 another fileset. 1453 Namespace: A filename/directory tree that a sufficiently-authorized 1454 client can observe. 1456 NSDB (Namespace Database Service): A service that maps FSNs to FSLs. 1457 The NSDB may also be used to store other information, such as 1458 annotations for these mappings and their components. 1460 NSDB Node: The name or location of a server that implements part of 1461 the NSDB service and is responsible for keeping track of the FSLs 1462 (and related info) that implement a given partition of the FSNs. 1464 Referral: A server response to a client access that directs the 1465 client to evaluate the current object as a reference to an object 1466 at a different location (specified by an FSL) in another fileset, 1467 and possibly hosted on another fileserver. The client re-attempts 1468 the access to the object at the new location. 1470 Replica: A replica is a redundant implementation of a fileset. Each 1471 replica shares the same FSN, but has a different FSL. 1473 Replicas may be used to increase availability or performance. 1474 Updates to replicas of the same fileset MUST appear to occur in 1475 the same order, and therefore each replica is self-consistent at 1476 any moment. 1478 We do not assume that updates to each replica occur simultaneously 1479 If a replica is offline or unreachable, the other replicas may be 1480 updated. 1482 Server Collection: A set of fileservers administered as a unit. A 1483 server collection may be administered with vendor-specific 1484 software. 1486 The namespace provided by a server collection could be part of the 1487 federated namespace. 1489 Singleton Server: A server collection containing only one server; a 1490 stand-alone fileserver. 1492 9. References 1494 9.1. Normative References 1496 [FEDFS-ADMIN] 1497 Lentini, J., Everhart, C., Ellard, D., Tewari, R., and M. 1498 Naik, "Administration Protocol for Federated Filesystems", 1499 draft-ietf-nfsv4-federated-fs-admin (Work In Progress), 1500 2009. 1502 [FEDFS-REQTS] 1503 Lentini, J., Everhart, C., Ellard, D., Tewari, R., and M. 1504 Naik, "Requirements for Federated File Systems", 1505 draft-ietf-nfsv4-federated-fs-reqts (Work In Progress), 1506 2009. 1508 [NFSv4.1] Shepler, S., Eisler, M., and D. Noveck, "NFS Version 4 1509 Minor Version 1", draft-ietf-nfsv4-minorversion1-29 (work 1510 in progress), December 2008. 1512 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1513 Requirement Levels", BCP 14, RFC 2119, March 1997. 1515 [RFC2203] Eisler, M., Chiu, A., and L. Ling, "RPCSEC_GSS Protocol 1516 Specification", RFC 2203, September 1997. 1518 [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. 1519 Schoenwaelder, Ed., "Structure of Management Information 1520 Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. 1522 [RFC2743] Linn, J., "Generic Security Service Application Program 1523 Interface Version 2, Update 1", RFC 2743, January 2000. 1525 [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 1526 Beame, C., Eisler, M., and D. Noveck, "Network File System 1527 (NFS) version 4 Protocol", RFC 3530, April 2003. 1529 [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally 1530 Unique IDentifier (UUID) URN Namespace", RFC 4122, 1531 July 2005. 1533 [RFC4510] Zeilenga, K., "Lightweight Directory Access Protocol 1534 (LDAP): Technical Specification Road Map", RFC 4510, 1535 June 2006. 1537 [RFC4511] Sermersheim, J., "Lightweight Directory Access Protocol 1538 (LDAP): The Protocol", RFC 4511, June 2006. 1540 [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol 1541 (LDAP): Directory Information Models", RFC 4512, 1542 June 2006. 1544 [RFC4513] Harrison, R., "Lightweight Directory Access Protocol 1545 (LDAP): Authentication Methods and Security Mechanisms", 1546 RFC 4513, June 2006. 1548 [RFC4516] Smith, M. and T. Howes, "Lightweight Directory Access 1549 Protocol (LDAP): Uniform Resource Locator", RFC 4516, 1550 June 2006. 1552 [RFC4517] Legg, S., "Lightweight Directory Access Protocol (LDAP): 1553 Syntaxes and Matching Rules", RFC 4517, June 2006. 1555 [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) 1556 Considerations for the Lightweight Directory Access 1557 Protocol (LDAP)", BCP 64, RFC 4520, June 2006. 1559 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1560 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1562 9.2. Informational References 1564 [AFS] Howard, J., "An Overview of the Andrew File System", 1565 Proceeding of the USENIX Winter Technical Conference , 1566 1988. 1568 [RFC1094] Nowicki, B., "NFS: Network File System Protocol 1569 specification", RFC 1094, March 1989. 1571 [RFC1813] Callaghan, B., Pawlowski, B., and P. Staubach, "NFS 1572 Version 3 Protocol Specification", RFC 1813, June 1995. 1574 [RFC3254] Alvestrand, H., "Definitions for talking about 1575 directories", RFC 3254, April 2002. 1577 Appendix A. Acknowledgments 1579 We would like to thank Andy Adamson of NetApp, Paul Lemahieu of EMC, 1580 Robert Thurlow of Sun Microsystems, and Mario Wurzl of EMC for 1581 helping to author this document. 1583 We would also like to thank George Amvrosiadis for pointing out that 1584 several LDAP attributes were missing the SINGLE-VALUE keyword in a 1585 draft version of this document. 1587 Authors' Addresses 1589 James Lentini 1590 NetApp 1591 1601 Trapelo Rd, Suite 16 1592 Waltham, MA 02451 1593 US 1595 Phone: +1 781-768-5359 1596 Email: jlentini@netapp.com 1598 Craig Everhart 1599 NetApp 1600 7301 Kit Creek Rd 1601 Research Triangle Park, NC 27709 1602 US 1604 Phone: +1 919-476-5320 1605 Email: everhart@netapp.com 1607 Daniel Ellard 1608 BBN Technologies 1609 10 Moulton Street 1610 Cambridge, MA 02138 1611 US 1613 Phone: +1 617-873-8000 1614 Email: dellard@bbn.com 1615 Renu Tewari 1616 IBM Almaden 1617 650 Harry Rd 1618 San Jose, CA 95120 1619 US 1621 Email: tewarir@us.ibm.com 1623 Manoj Naik 1624 IBM Almaden 1625 650 Harry Rd 1626 San Jose, CA 95120 1627 US 1629 Email: manoj@almaden.ibm.com