RFC 7532
Namespace Database (NSDB) Protocol for Federated File Systems
RFC 7532: Namespace Database (NSDB) Protocol for Federated File Systems 🎀
Okay bestie, here's the header info 📋✨ This is an IETF Standards Track doc, written by J. Lentini (NetApp), R. Tewari (IBM Almaden), and C. Lever, Ed. (Oracle Corporation). It's dated March 2015 and its ISSN is 2070-1721. The header doesn't list anything it obsoletes or updates, so it's standing completely on its own 💅
Abstract ✨
This doc is all about a file system federation protocol that makes file access and namespace traversal work across groups of fileservers that are each run by different admins 🦋 The protocol gives fileservers with different administrators a set of interfaces to form a fileserver federation. That federation provides a namespace built from the file systems physically hosted on and exported by the fileservers it's made of. So many moving parts, and it's giving teamwork 🫶
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741.
Want the latest status, errata, or a way to send feedback? Check out http://www.rfc-editor.org/info/rfc7532 🌸
Copyright Notice
Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, because they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they are provided without warranty as described in the Simplified BSD License. 📜
This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English. 🙈
Table of Contents 🧚
1. Introduction ....................................................4
1.1. Requirements Language ......................................5
2. Overview of Features and Concepts ...............................5
2.1. File-Access Protocol .......................................5
2.2. File-Access Client .........................................5
2.3. Fileserver .................................................5
2.4. Referral ...................................................5
2.5. Namespace ..................................................6
2.6. Fileset ....................................................6
2.7. Fileset Name (FSN) .........................................6
2.8. Fileset Location (FSL) .....................................7
2.8.1. The NFS URI Scheme ..................................8
2.8.2. Mutual Consistency across Fileset Locations ........10
2.8.3. Caching of Fileset Locations .......................11
2.8.4. Generating a Referral from Fileset Locations .......12
2.9. Namespace Database (NSDB) .................................13
2.9.1. NSDB Client ........................................14
2.10. Junctions and Referrals ..................................14
2.11. Unified Namespace and the Root Fileset ...................15
2.12. UUID Considerations ......................................15
3. Examples .......................................................16
3.1. Creating a Fileset and Its FSL(s) .........................16
3.1.1. Creating a Fileset and an FSN ......................17
3.1.2. Adding a Replica of a Fileset ......................17
3.2. Junction Resolution .......................................17
3.3. Example Use Cases for Fileset Annotations .................18
4. NSDB Configuration and Schema ..................................19
4.1. LDAP Configuration ........................................19
4.2. LDAP Schema ...............................................21
4.2.1. LDAP Attributes ....................................23
4.2.2. LDAP Object Classes ................................38
5. NSDB Operations ................................................42
5.1. NSDB Operations for Administrators ........................43
5.1.1. Create an FSN ......................................43
5.1.2. Delete an FSN ......................................44
5.1.3. Create an FSL ......................................44
5.1.4. Delete an FSL ......................................47
5.1.5. Update an FSL ......................................48
5.2. NSDB Operations for Fileservers ...........................49
5.2.1. NSDB Container Entry (NCE) Enumeration .............49
5.2.2. Lookup FSLs for an FSN .............................49
5.3. NSDB Operations and LDAP Referrals ........................50
6. Security Considerations ........................................51
7. IANA Considerations ............................................52
7.1. Registry for the fedfsAnnotation Key Namespace ............52
7.2. Registry for FedFS Object Identifiers .....................52
7.3. LDAP Descriptor Registration ..............................55
8. Glossary .......................................................58
9. References .....................................................60
9.1. Normative References ......................................60
9.2. Informative References ....................................62
Acknowledgments ...................................................64
Authors' Addresses ................................................651. Introduction ✨
A federated file system lets you do file access and namespace traversal in a way that's uniform, secure, and consistent 💖 It works across lots of independent fileservers, whether they live inside one enterprise or span several enterprises at once.
This document specifies a set of protocols that let fileservers cooperate to form a federation containing one or more federated file systems. The fileservers might come from different vendors and have different administrators, and that's totally fine 🧚 Each federated file system's namespace is built from the file systems physically hosted on and exported by the federation's fileservers. A federation has a common namespace across all of its fileservers. It can project multiple namespaces, and clients can traverse each one. It can also hold an arbitrary number of namespace repositories, each belonging to a different administrative entity and each rendering a part of the namespace. And a federation might have an arbitrary number of administrative entities, each responsible for administering a disjoint subset of the fileservers.
Building a namespace that spans multiple fileservers has been hard for two big reasons 😤 First, the fileservers that export pieces of the namespace are often not in the same administrative domain. Second, there's no standard mechanism for the fileservers to cooperatively present the namespace. Fileservers may come with proprietary management tools, and sometimes an administrator can use those tools to build a shared namespace out of the exported file systems. But relying on vendor-specific proprietary tools doesn't work in larger enterprises, or when collaborating across enterprises. The fileservers are likely to be from multiple vendors or use different software versions, each with its own namespace protocols, and there's no common mechanism to manage the namespace or exchange namespace information. Major mood 💀
The federated file system protocols in this document define how to construct a namespace that's accessible by a Network File System (NFS) version 4.0 [RFC7530], NFSv4.1 [RFC5661], or newer client. They were also designed to accommodate other file-access protocols in the future 🌈
The requirements for federated file systems are described in [RFC5716]. A protocol for administering a fileserver's namespace is described in [RFC7533]. The mechanism for discovering the root of a federated namespace is described in [RFC6641].
In the rest of the document, the term "fileserver" denotes a fileserver that is part of a federation.
1.1. Requirements Language 🔥
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].
2. Overview of Features and Concepts 👑
2.1. File-Access Protocol 🎀
A file-access protocol is a network protocol for accessing data. The NFSv4.0 protocol [RFC7530] is an example of a file-access protocol.
2.2. File-Access Client 🦋
File-access clients are standard, off-the-shelf network-attached storage (NAS) clients that communicate with fileservers using a standard file-access protocol.
2.3. Fileserver 🍓
Fileservers are servers that store physical fileset data or refer file-access clients to other fileservers. A fileserver provides access to its shared file system data via a file-access protocol. A fileserver may be implemented in a number of different ways, including a single system, a cluster of systems, or some other configuration.
2.4. Referral ✨
A referral is a mechanism by which a fileserver redirects a file-access client to a different fileserver or export. The exact information contained in a referral varies from one file-access protocol to another. The NFSv4.0 protocol, for example, defines the fs_locations attribute for returning referral information to NFSv4.0 clients. The NFSv4.1 protocol introduces the fs_locations_info attribute, which can return richer referral information to its clients. NFSv4.1 fileservers may use either attribute during a referral. Both attributes are defined in [RFC5661]. Okay, that's the setup done, and the real fun starts next 💜
2.5. Namespace 🗺️
okay so the whole point of a unified namespace is that all managed data shows up at the same path in one common file system namespace, no matter which file-access client is looking 💖. This should be achieved with minimal or zero configuration on file-access clients ✨. Like, updates to the common namespace should not require configuration changes to any file-access client. the clients just vibe and it works 💅.
Filesets (the units of data management) are a set of files and directories 🌸. From a file-access client's perspective, the common namespace gets built by mounting filesets that are physically sitting on different fileservers 🦋. The namespace is defined in terms of fileset names and locations, and it's stored in a set of namespace repositories, each managed by its own administrative entity 👑.
The namespace schema is the model used for populating, modifying, and querying those namespace repositories 🧚. The federation doesn't require the namespace to be common across all fileservers, though. It should be possible to have several independently rooted namespaces 🌈.
2.6. Fileset 📁
A fileset is loosely defined as a set of files and the directory tree that contains them 🎀. It's the basic unit of data management, the main character of this whole story ✨. Depending on the configuration, a fileset can be anything from an individual directory of an exported file system to an entire exported file system on a fileserver 💅.
2.7. Fileset Name (FSN) 🏷️
A fileset is uniquely represented by its fileset name (FSN) 💜. An FSN is considered unique across a federation. Once an FSN is created, it's associated with one or more fileset locations (FSLs) on one or more fileservers 🦋.
An FSN consists of:
- NsdbName: the network location of the Namespace Database (NSDB) node that contains authoritative information for this FSN.
- FsnUuid: a UUID (universally unique identifier), conforming to [RFC4122], that is used to uniquely identify an FSN.
- FsnTTL: the time-to-live of the FSN's FSL information, in seconds. Fileservers MUST NOT use cached FSL records after the parent FSN's FsnTTL has expired. An FsnTTL value of zero indicates that fileservers MUST NOT cache the results of resolving this FSN. 🙅♀️
The NsdbName isn't physically stored as an attribute of the record 🙈. It's obvious to any client that accesses an NSDB, and it's indeed authenticated in cases where Transport Layer Security (TLS) is in effect 🔒.
The FsnUuid and NsdbName values never change during an FSN's lifetime 💎. However, an FSN's FSL information can change over time, and it's typically cached on fileservers for performance ⚡. More detail on FSL caching is in Section 2.8.3 🧠.
An FSN record may also contain:
- Annotations: name/value pairs that can be interpreted by a fileserver. The semantics of this field are not defined by this document. These tuples are intended to be used by higher-level protocols.
- Descriptions: text descriptions. The semantics of this field are not defined by this document.
2.8. Fileset Location (FSL) 📍
An FSL describes one physical location where a complete copy of the fileset's data resides 🗂️. It holds generic and type-specific information that together explain how to access the fileset data at this location. A fileserver can use an FSL's attributes to decide which locations it will return to a file-access client 🎯.
An FSL consists of:
- FslUuid: a UUID, conforming to [RFC4122], that is used to uniquely identify an FSL.
- FsnUuid: the UUID of the FSL's FSN.
- NsdbName: the network location of the NSDB node that contains authoritative information for this FSL.
The NsdbName isn't stored as an attribute of an FSL record, for the same reason it isn't stored in FSN records 🙃.
An FSL record may also contain:
- Annotations: name/value pairs that can be interpreted by a fileserver. The semantics of this field are not defined by this document. These tuples are intended to be used by higher-level protocols.
- Descriptions: text descriptions. The semantics of this field are not defined by this document.
On top of the attributes above, an FSL record contains attributes that let a fileserver construct referrals 🪄. For each file-access protocol, there's a corresponding FSL record subtype.
This document defines an FSL subtype for NFS. An NFS FSL contains information suitable for use in one of the NFSv4 referral attributes (e.g., fs_locations or fs_locations_info, described in [RFC5661]). Section 4.2.2.4 describes the contents of an NFS FSL record 📜.
A fileset may also be accessible by file-access protocols other than NFS 🌍. The contents and format of such FSL subtypes are not defined in this document.
2.8.1. The NFS URI Scheme 🌐
To capture the location of an NFSv4 fileset, we extend the NFS URL scheme specified in [RFC2224] 🔧. This extension follows the rules for defining Uniform Resource Identifier schemes (see [RFC3986]). From here on, we'll refer to this extended NFS URL scheme as an NFS URI 💫.
An NFS URI MUST contain both an authority and a path component. It MUST NOT contain a query component or a fragment component 🚫. Use of the familiar nfs scheme name is retained, so no rebranding drama here 🥰.
2.8.1.1. The NFS URI Authority Component 🏛️
The rules for encoding the authority component of a generic URI are specified in section 3.2 of [RFC3986]. The authority component of an NFS URI MUST contain the host subcomponent. For globally scoped NFS URIs, a hostname used in such URIs SHOULD be a fully qualified domain name. See section 3.2.2 of [RFC3986] for rules on encoding non-ASCII characters in hostnames 🌏.
An NFS URI MAY contain a port subcomponent, as described in section 3.2.3 of [RFC3986]. If this subcomponent is missing, a port value of 2049 is assumed, as specified in [RFC7530], Section 3.1 🔢.
2.8.1.2. The NFS URI Path Component 🛤️
The rules for encoding the path component of a generic URI are specified in Section 3.3 of [RFC3986].
According to Sections 5 and 6 of [RFC2224], NFS URLs specify a pathname relative to an NFS fileserver's public filehandle. But NFSv4 fileservers don't expose a public filehandle, so that's a plot twist 😭. Instead, NFSv4 pathnames contained in an NFS URI are evaluated relative to the pseudoroot of the fileserver identified in the URI's authority component 🌱.
Each component of an NFSv4 pathname is represented as a component4 string (see Section 3.2, "Basic Data Types", of [RFC5661]). The component4 elements of an NFSv4 pathname are encoded as path segments in an NFS URI 🧩. NFSv4 pathnames MUST be expressed in an NFS URI as an absolute path. An NFS URI path component MUST NOT be empty. The NFS URI path component starts with a slash (/) character, followed by one or more path segments that each start with a slash (/) character [RFC3986].
Therefore, a double slash always follows the authority component of an NFS URI. For example, the NFSv4 pathname "/" is represented by two slash (/) characters following an NFS URI's authority component, so it looks like // 🥹.
The component names of an NFSv4 pathname MUST be prepared using the component name rules defined in Section 12 ("Internationalization") of [RFC7530] prior to encoding the path component of an NFS URI 🌈. As specified in [RFC3986], any non-ASCII characters and any URI-reserved characters, such as the slash (/) character, contained in a component4 element MUST be represented by URI percent encoding 🫶.
2.8.1.3. Encoding an NFS Location in an FSL 🧩
The path component of an NFS URI encodes the rootpath field of the NFSv4 fs_location4 data type, or the fli_rootpath of the NFSv4 fs_locations_item4 data type (see [RFC5661]) 🗺️.
In its server field, the NFSv4 fs_location4 data type contains a list of universal addresses and DNS labels. Each may optionally include a port number. The exact encoding requirements for this information are found in Section 12.6 of [RFC7530]. The NFSv4 fs_locations_item4 data type encodes the same data in its fli_entries field (see [RFC5661]). This information is encoded in the authority component of an NFS URI 💅.
The server and fli_entries fields can encode multiple server hostnames that share the same pathname. An NFS URI, and hence an FSL record, represents only a single hostname and pathname pair 👯. An NFS fileserver MUST NOT combine a set of FSL records into a single fs_location4 or fs_locations_item4 unless each FSL record in the set contains the same rootpath value and extended file system information 🚫✨.
2.8.2. Mutual Consistency across Fileset Locations 🤝
All of the FSLs that have the same FSN (and thereby reference the same fileset) are equivalent from the point of view of access by a file-access client 💞. Different fileset locations for an FSN represent the same data, though potentially at different points in time. So they're equivalent but not identical 👀. Locations may be either read-only or read-write. Typically, multiple read-write locations are backed by a clustered file system, while read-only locations are replicas created by a federation-initiated or external replication operation 🪞. Read-only locations may represent consistent point-in-time copies of a read-write location. The federation protocols, however, can't prevent subsequent changes to a read-only location, nor guarantee point-in-time consistency of a read-only location if the read-write location is changing 😬.
Regardless of type, one file-access client may be referred to a location described by one FSL, while another client chooses to use a location described by another FSL 🔀. Since updates to each fileset location aren't controlled by the federation protocol, it's the responsibility of administrators to guarantee the functional equivalence of the data 🧑💼.
The federation protocols don't guarantee that different fileset locations are mutually consistent in terms of the currency of their data. However, they provide a means to publish currency information so that all fileservers in a federation can convey the same information to file-access clients during referrals 📣. Clients use this information to make sure they don't revert to an out-of-date version of a fileset's data when switching between fileset locations ⏪🚫. NFSv4.1 provides guidance on how replication can be handled in such a manner. In particular, see Section 11.7 of [RFC5661] 📚.
2.8.3. Caching of Fileset Locations ⏳
okay so when a fileserver wants to turn an FSN into a set of FSL records, it asks the NSDB node named in that FSN for the FSL records tied to it 📚. The parent FSN's FsnTTL attribute (see Section 2.7) tells the fileserver how long it's allowed to cache those FSL records ⏰.
The combo of FSL caching and FSL migration is kinda tricky ngl 😬. Picture this: three fileservers, A, B, and C. Fileserver A has a junction J pointing at fileset X, which lives on fileserver B (see Section 2.10 for what junctions are) 🦋.
Now fileset X gets migrated from fileserver B to fileserver C, and the FSL info for fileset X in the authoritative NSDB gets updated ✨.
If fileserver A has cached FSLs for fileset X, a file-access client that walks through junction J on fileserver A gets referred to fileserver B... even though X already moved to C 💀. If A hadn't cached the FSL records, it would've asked the NSDB and gotten the right location for X. Oof 🙈.
Migration usually leaves a redirection behind on the source fileserver where the migrated fileset used to be 🎀. Without it, clients would just find an empty space where the fileset was, and that totally defeats the whole point of a managed migration 😤.
That redirection could be a new junction that targets the same FSN as the other junctions pointing at the migrated fileset. Or it could be some other kind of directive, depending on the fileserver implementation. Either way, it just tells clients where fileset X moved to 🧭.
Back to our drama. Say that during migration, a junction replaces fileset X on fileserver B. Later, one of two things happens:
- New file-access clients get sent to fileserver B because of stale FSL info cached on fileserver A, or
- File-access clients keep hitting fileserver B because they've cached stale location data for fileset X.
In both cases, thanks to the redirection, fileserver B tells the clients that fileset X has moved to fileserver C 🫶.
Those redirecting junctions (here, the ones on fileserver B) aren't meant to stick around forever 🥲. They need to stay put at least until the FSL entries cached on fileservers, and the locations cached on file-access clients for the target fileset, have been invalidated.
The FsnTTL field in the FSL's parent FSN (see Section 2.7) sets an upper bound on how long cached FSL info can live. That means it can act as a lower bound on how long redirecting junctions should last 📏.
For example, suppose the FsnTTL field contains the value 3600 seconds (one hour). In that case, administrators SHOULD keep the redirection in place for at least one hour after a fileset migration has taken place, because a referring fileserver might cache the FSL data during that time before refreshing it ⏳.
bestie, the TTL is basically the timer for how long that redirect has to hang around. Don't yeet it early 😭
To get file-access clients to the destination fileserver more quickly, administrators SHOULD set the FsnTTL field of the migrated fileset to a low number or zero before migration begins 🏃♀️. It can be reset to a more reasonable number at a later point 💅.
Note that some file-access protocols don't communicate location cache expiry info to file-access clients 🙃. In some cases, it may be difficult to figure out an appropriate lifetime for redirecting junctions, because file-access clients may cache location info indefinitely 😭.
2.8.4. Generating a Referral from Fileset Locations 🧾
After the fileserver resolves an FSN into a set of FSL records, it generates a referral to redirect a file-access client to one or more of the FSN's FSLs 🎁. It converts the FSL records into a referral format that the particular file-access client understands, like an NFSv4 fs_locations or fs_locations_info attribute 🔧.
To give file-access clients as many options as possible, the fileserver SHOULD include the maximum possible number of FSL records in a referral 🌈. That said, the fileserver MAY omit some of the FSL records 🤷♀️. For example, it might leave out an FSL record because of limitations in the file-access protocol's referral format 🙃.
For a given FSL record, the fileserver MAY convert or reduce its contents in a way that fits the referral format 💫. Like, an NFS FSL record has all the data needed to construct an fs_locations_info attribute, but fs_locations_info holds info that isn't in the simpler fs_locations attribute 🧠. So the fileserver builds fs_locations entries using the relevant contents of an NFS FSL record 💅.
Whenever the fileserver converts or reduces FSL data, it SHOULD try to keep the original meaning where possible ✨. For example, an NFS FSL record includes the rank and order info that appears in an fs_locations_info attribute (see NFSv4.1's FSLI4BX_READRANK, FSLI4BX_READORDER, FSLI4BX_WRITERANK, and FSLI4BX_WRITEORDER) 📊. That rank and order info isn't explicitly expressible in an fs_locations attribute, but the fileserver can arrange the fs_locations attribute's locations list based on the rank and order values 🪄.
Another one: a single NFS FSL record contains the hostname of one fileserver, while a single fs_locations attribute can contain a list of fileserver names 🍓. An NFS fileserver MAY combine two or more FSL records into a single entry in an fs_locations or fs_locations_info array, but only if each FSL record contains the same pathname and extended file system information 🔒.
For more details, check Sections 11.9 and 11.10 of the NFSv4.1 protocol specification [RFC5661] 📖.
2.9. Namespace Database (NSDB) 🗄️
The NSDB service is a federation-wide service that provides interfaces to define, update, and query FSN information, FSL information, and FSN-to-FSL mapping information 💁♀️.
An individual repository of namespace information is called an NSDB node 📦. The difference between the NSDB service and an NSDB node is kinda like the difference between the DNS service and a particular DNS server 🌐.
Each NSDB node is managed by a single administrative entity. A single administrative entity can manage multiple NSDB nodes 👑.
Each NSDB node stores the definition of the FSNs it's authoritative for, plus the definitions of the FSLs associated with those FSNs. An NSDB node is authoritative for the filesets it defines 🧾.
An NSDB MAY be replicated throughout the federation 🌍. If an NSDB is replicated, the NSDB MUST exhibit loose, converging consistency as defined in [RFC3254] 🫧. The mechanism that achieves this is outside the scope of this document 🙅♀️. Many Lightweight Directory Access Protocol (LDAP) implementations support replication. These features MAY be used to replicate the NSDB 💜.
2.9.1. NSDB Client 💻
Each NSDB node supports an LDAP [RFC4510] interface. An NSDB client is software that uses the LDAP protocol to access or update namespace information stored on an NSDB node 🔍.
A domain's administrative entity uses NSDB client software to manage information stored on NSDB nodes. More on these transactions in Section 5.1 📝.
Fileservers act as an NSDB client when they contact a particular NSDB node to resolve an FSN into a set of FSL records. The resulting location info is then passed to file-access clients via referrals 🎀. So file-access clients never need to access NSDBs directly. These transactions are described in Section 5.2 🙌.
2.10. Junctions and Referrals 🦋
A junction is a point in a particular fileset namespace where a specific target fileset may be attached 🪝. If a file-access client traverses the path leading from the root of a federated namespace to the junction referring to a target fileset, it should be able to mount and access the data in that target fileset (assuming appropriate permissions) 🔐. In other words, a junction can be viewed as a reference from a directory in one fileset to the root of the target fileset 💖.
A junction can be implemented as a special marker on a directory, or by some other mechanism in the fileserver's underlying file system 🛠️. What data the fileserver uses to represent junctions isn't defined by this document. The essential property is that, given a junction, a fileserver must be able to find the FSN for the target fileset 🔑.
When a file-access client reaches a junction, the fileserver refers the client to a list of FSLs associated with the FSN targeted by the junction. The client can then mount one of the associated FSLs 🧚.
The federation protocols don't limit where, or how many times, a fileset is mounted in the namespace 🌸. Filesets can be nested, so a fileset can be mounted under another fileset 🪆.
2.11. Unified Namespace and the Root Fileset 🌟
The root fileset, when defined, is the top-level fileset of the federation-wide namespace 👑. The root of the unified namespace is the top-level directory of this fileset. A set of designated fileservers in the federation can export the root fileset to render the federation-wide unified namespace 🎀. When a file-access client mounts the root fileset from any of these designated fileservers, it can view a common federation-wide namespace 💕.
2.12. UUID Considerations ✨
okay bestie, so FedFS uses UUIDs that follow [RFC4122] to make sure FSN and FSL records are unique across a whole domain 🆔. Those UUIDs form the distinguished names of the LDAP records that hold FedFS data (see Section 4.2.2.2) 💖.
Junctions store a tuple with an FSN UUID and the name and port of an NSDB node, so an FSN UUID only has to be unique on a single NSDB node 🎀. You can catch a collision right away when an admin tries to publish an FSN or FSL by storing it under a specific NSDB Container Entry (NCE) on an authoritative NSDB host ✨.
One NSDB node can hold more than one NCE, each under a different namingContext 🌸. If a node has to contain more than one NCE, the federation's admin entity SHOULD provide a robust method for preventing FSN UUID collisions between FSNs that live on the same NSDB node but under different NCEs 💅.
FSLs are children of FSNs, so FSL UUIDs only need to be unique within a single FSN 🦋. Same as FSNs, uniqueness is guaranteed as soon as an FSL is published 🫶.
A fileserver performs the operations described in Section 5.2 as an unauthenticated user 🙈. So the distinguished names of FSN and FSL records, plus the FSN and FSL records themselves, are required to be readable by anyone who can bind anonymously to an NSDB node 😭. Therefore, FSN and FSL UUIDs should be considered public information 🌈.
Version 1 UUIDs contain a host's Media Access Control (MAC) address and a timestamp in the clear 👀. That gives provenance to each UUID, but attackers can use those details to guess things about the host where the UUID was generated 💀. Security-sensitive installations should be aware that on externally facing NSDBs, UUIDs can reveal information about the hosts where they are generated. 🚨
Version 1 UUIDs also depend on the idea that a hardware MAC address is unique across machines 🤔. Virtual machines don't depend on unique physical MAC addresses, and anyway an administrator can modify the physical MAC address. So version 1 UUIDs are no longer considered sufficient 🙅♀️.
To minimize the probability of UUID collisions, a consistent procedure for generating UUIDs should be used throughout a federation 🧚. Within a federation, UUIDs SHOULD be generated using the procedure described for version 4 of the UUID variant specified in [RFC4122] 🔥.
3. Examples ✨
In this section we walk through examples and discussion of the basic operations the federated file system protocol makes possible: creating a fileset, adding a replica of a fileset, resolving a junction, and creating a junction 🍓.
3.1. Creating a Fileset and Its FSL(s) 📁
A fileset is the abstraction of a set of files and the directory tree that contains them 🌷. It's the fundamental unit of data management in the federation 👑. The abstraction is implemented by an actual directory tree whose root location is specified by a fileset location (FSL) 💜.
Here we describe the basic requirements for starting with a directory tree and creating a fileset that can be used in the federation protocols 🎀. Heads up, we don't assume that creating a fileset requires any transformation of the files or the directory hierarchy 🙌. The only things this process requires are assigning the fileset a fileset name (FSN) and expressing the location of the fileset's implementation as an FSL 💅.
There are lots of possible variations on this procedure, depending on how the FSN that binds the FSL is created, and on whether other replicas of the fileset exist, are known to the federation, and need to be bound to the same FSN 🦋.
It's easiest to explain it by looking at how to create the initial implementation of the fileset first, then how to add replicas 🫶.
3.1.1. Creating a Fileset and an FSN 🏗️
The following administrative steps create an FSN, which is used to track all replicas of a single physical dataset 💖.
- Choose the NSDB node that will keep track of the FSL(s) and related information for the fileset.
- Create an FSN in the NSDB node.
The FSN UUID is chosen by the administrator or generated automatically by administration software. The former is used if the fileset is being restored, perhaps as part of disaster recovery, and the administrator wants to specify the FSN UUID so that existing junctions that reference that FSN work again 🔁.
At this point the FSN exists, but its fileset locations are unspecified 🤷♀️.
- For the FSN created above, create an FSL in the NSDB node that describes the physical location of the fileset data 📍.
3.1.2. Adding a Replica of a Fileset 👯♀️
Adding a replica is super straightforward: the NSDB node and the FSN are already known 😌. The only remaining step is to add another FSL ✨.
Note that the federation protocols only provide the mechanisms to register and unregister replicas of a fileset 🙃. Fileserver-to-fileserver replication protocols are not defined 🚫.
3.2. Junction Resolution 🔗
A fileset may contain references to other filesets, and these references are represented by junctions 🧩. If a file-access client requests access to a fileset object that is a junction, the fileserver resolves the junction to discover one or more FSLs that implement the referenced fileset 🕵️♀️.
There are lots of possible variations on this procedure, depending on how the fileserver represents junctions and how it performs junction resolution 🌈.
Step 4 is the only step that interacts directly with the federation protocols 💫. The rest of the steps may use platform-specific interfaces 🛠️.
- The fileserver determines that the object being accessed is a junction.
- The fileserver does a local lookup to find the FSN of the target fileset.
- Using the FSN, the fileserver finds the NSDB node responsible for the target FSN.
- The fileserver contacts that NSDB node and asks for the set of FSLs that implement the target FSN. The NSDB node responds with a (possibly empty) set of FSLs 📬.
- The fileserver converts one or more of the FSLs to the location type used by the file-access client (e.g., an NFSv4
fs_locationsattribute as described in [RFC5661]) 🔄. - The fileserver redirects the client to the location(s), in whatever manner is appropriate for the client 🏃♀️💨.
3.3. Example Use Cases for Fileset Annotations 🏷️
Fileset annotations can convey extra attributes of a fileset 💌. For example, they can define relationships between filesets that an auxiliary replication protocol can use 🤓. Picture this: a fileset gets created and mounted at some point in the namespace. A snapshot of that fileset's read-write FSL is taken periodically at different frequencies (say, a daily or weekly snapshot), and the different snapshots are mounted at different locations in the namespace 📸.
The daily snapshots count as different filesets from the weekly ones, but both are related to the source fileset 👭. We can define an annotation that labels the filesets as source and replica 🏷️. The replication protocol can use that info to copy data from one or more FSLs of the source fileset to all the FSLs of the replica fileset 🚚. The replica filesets are read-only, while the source fileset is read-write 🔒.
This follows the traditional Andrew File System (AFS) model of mounting the read-only volume at a path in the namespace that's different from the one used for the read-write volume [AFS] 💅.
The federation protocol doesn't control or manage the relationship among filesets 🙅♀️. It only enables annotating the filesets with user-defined relationships 🎨.
Another potential use for annotations is recording references to an FSN 🔍. You could define a single annotation containing the number of references, or multiple annotations, one per reference, to store detailed information about the location of each reference 📚.
Just like the replication annotation above, the maintenance of reference information isn't controlled by the federation protocol 🙈. The information would most likely be non-authoritative, because the ability to create a junction doesn't require the authority to update the FSN record 🫠. Either way, such annotations could be useful to admins for figuring out whether a junction references an FSN 🕵️.
4. NSDB Configuration and Schema 🗂️
This section describes how an NSDB is built using an LDAP Version 3 [RFC4510] directory 💻. Section 4.1 covers the basic properties of the LDAP configuration that MUST be used to keep different implementations compatible 🫶. Section 4.2 defines the new LDAP attribute types and the new object types, and it also specifies how the distinguished name (DN) of each object instance MUST be constructed 💖✨.
4.1. LDAP Configuration 🦋
Okay bestie, so an NSDB gets built on top of an LDAP directory 💅. This directory MAY have multiple naming contexts. The directory's rootDSE entry (the special entry for Digital Signature Algorithm (DSA)) has a multi-valued namingContext attribute, and each value in it is the DN of a naming context's root entry (see [RFC4512]) 🌸.
For each naming context that has federation entries (like FSNs and FSLs) 🧚:
- There MUST be an LDAP entry that sits above all of that naming context's federation entries in the Directory Information Tree (DIT). It's called the NSDB Container Entry (NCE). The NCE's children are FSNs, and an FSN's children are FSLs 💖.
- The naming context's root entry MUST include "fedfsNsdbContainerInfo" (defined in Section 4.2.2.1) as one of its object classes. The fedfsNsdbContainerInfo's fedfsNceDN attribute is how you find that naming context's NCE 🔍.
If a naming context doesn't have any federation entries, then it won't have an NCE, and its root entry won't have "fedfsNsdbContainerInfo" as one of its object classes. Totally fine, not every context needs to be in the drama 🙈.
A fedfsNsdbContainerInfo's fedfsNceDN attribute holds the distinguished name (DN) of the NSDB Container Entry living under that naming context. The fedfsNceDN attribute MUST NOT be empty ✨.
Here's an example of what an LDAP directory might look like 👑:
-+ [root DSE]
| namingContext: o=fedfs
| namingContext: dc=example,dc=com
| namingContext: ou=system
|
|
+---- [o=fedfs]
| fedfsNceDN: o=fedfs
|
|
+---- [dc=example,dc=com]
| fedfsNceDN: ou=fedfs,ou=corp-it,dc=example,dc=com
|
|
+---- [ou=system]So in this case, the "o=fedfs" namingContext has its NSDB Container Entry at "o=fedfs", the "dc=example,dc=com" namingContext has its NCE at "ou=fedfs,ou=corp-it,dc=example,dc=com", and the "ou=system" namingContext has no NCE at all 🌈.
The NSDB SHOULD be set up with one or more privileged LDAP users. These users are the ones who can change what's in the LDAP database 🔐. An administrator doing the operations described in Section 5.1 SHOULD authenticate using the DN of a privileged LDAP user 🫶.
It MUST be possible for an unprivileged (unauthenticated) user to run LDAP queries that get to the NSDB data. A fileserver does the operations described in Section 5.2 as an unprivileged user, so this part is non-negotiable 💅.
All implementations SHOULD use the same schema. At minimum, each MUST use a schema that includes all of the objects named in the following sections, with all of their associated attributes 📚. If an implementation really needs to extend the schema defined here, you can do it in one of these ways 🎀:
- Define a fedfsAnnotation key and values (see Section 4.2.1.6). Then register the new key and values with IANA (see Section 7.1).
- Define additional attribute types and object classes, then have entries inherit from a class defined in this document and from the implementation-defined ones.
So given all of that, an NSDB SHOULD be built on a dedicated LDAP server 💖. If you need LDAP directories for other stuff, like storing user account info, then using a separate LDAP server for that is RECOMMENDED. Having a server that only stores NSDB records means you never have to mess with the config of other LDAP directories holding things that have nothing to do with the NSDB 🌸.
4.2. LDAP Schema ✨
The schema definitions in this document use the LDAP schema syntax defined in [RFC4512] 🧚. They're formatted so you can easily pull them out of the document. The reader can use this shell script to extract them 🍓:
<CODE BEGINS>
#!/bin/sh
grep '^ *///' | sed 's?^ */// ??' | sed 's?^ *///$??'
<CODE ENDS>Say the script is saved in a file called "extract.sh", and this document is in a file called "spec.txt". Then the reader can run:
<CODE BEGINS>
sh extract.sh < spec.txt > fedfs.schema
<CODE ENDS>What the script does is strip the leading white space from each line, plus the sentinel sequence of "///" 🦋.
Code components pulled out of this document must include the following license 📜:
<CODE BEGINS>
/// #
/// # Copyright (c) 2015 IETF Trust and the persons identified
/// # as authors of the code. All rights reserved.
/// #
/// # The authors of the code are:
/// # J. Lentini, C. Everhart, D. Ellard, R. Tewari, and M. Naik.
/// #
/// # Redistribution and use in source and binary forms, with
/// # or without modification, are permitted provided that the
/// # following conditions are met:
/// #
/// # - Redistributions of source code must retain the above
/// # copyright notice, this list of conditions and the
/// # following disclaimer.
/// #
/// # - Redistributions in binary form must reproduce the above
/// # copyright notice, this list of conditions and the
/// # following disclaimer in the documentation and/or other
/// # materials provided with the distribution.
/// #
/// # - Neither the name of Internet Society, IETF or IETF
/// # Trust, nor the names of specific contributors, may be
/// # used to endorse or promote products derived from this
/// # software without specific prior written permission.
/// #
/// # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS
/// # AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
/// # WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
/// # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
/// # FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
/// # EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
/// # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
/// # EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
/// # NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
/// # SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
/// # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
/// # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
/// # OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
/// # IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
/// # ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
/// #
<CODE ENDS>4.2.1. LDAP Attributes 💜
The following definitions are used in this document:
- The name attribute described in [RFC4519].
- The Integer syntax (1.3.6.1.4.1.1466.115.121.1.27) described in [RFC4517].
- The integerMatch rule described in [RFC4517].
- The Octet String syntax (1.3.6.1.4.1.1466.115.121.1.40) described in [RFC4517].
- The octetStringMatch rule described in [RFC4517].
- The Boolean syntax (1.3.6.1.4.1.1466.115.121.1.7) described in [RFC4517].
- The booleanMatch rule described in [RFC4517].
- The distinguishedNameMatch rule described in [RFC4517].
- The DN syntax (1.3.6.1.4.1.1466.115.121.1.12) described in [RFC4517].
- The labeledURI attribute described in [RFC2079].
- The UUID syntax (1.3.6.1.1.16.1) described in [RFC4530].
- The UuidMatch rule described in [RFC4530].
- The UuidOrderingMatch rule described in [RFC4530].
4.2.1.1. fedfsUuid 🔑
A fedfsUuid is the base type for all of the universally unique identifiers (UUIDs) the federated file system protocols use 🌸.
The fedfsUuid type is based on rules and syntax defined in [RFC4530].
A fedfsUuid is a single-valued LDAP attribute.
<CODE BEGINS>
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.1 NAME 'fedfsUuid'
/// DESC 'A UUID used by NSDB'
/// EQUALITY uuidMatch
/// ORDERING uuidOrderingMatch
/// SYNTAX 1.3.6.1.1.16.1
/// SINGLE-VALUE
/// )
///
<CODE ENDS>4.2.1.2. fedfsFsnUuid 🎀
A fedfsFsnUuid represents the UUID component of an FSN. An NSDB SHOULD ensure that no two FSNs it stores have the same fedfsFsnUuid 💅.
This attribute is single-valued.
<CODE BEGINS>
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.4 NAME 'fedfsFsnUuid'
/// DESC 'The FSN UUID component of an FSN'
/// SUP fedfsUuid
/// SINGLE-VALUE
/// )
///
<CODE ENDS>4.2.1.3. fedfsFsnTTL ⏳
A fedfsFsnTTL is the time-to-live in seconds of a cached FSN and its child FSL records. It corresponds to the FsnTTL as defined in Section 2.7. See also Section 2.8.3 for info about caching FSLs 🧠. A fedfsFsnTTL MUST be encoded as an Integer syntax value [RFC4517] in the range [0, 4294967295] 🔢.
This attribute is single-valued.
<CODE BEGINS>
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.11 NAME 'fedfsFsnTTL'
/// DESC 'Time to live of an FSN tree'
/// EQUALITY integerMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
/// SINGLE-VALUE
/// )
///
<CODE ENDS>OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517].
4.2.1.4. fedfsNceDN 🗂️
A fedfsNceDN stores a distinguished name (DN).
This attribute is single-valued.
<CODE BEGINS>
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.14 NAME 'fedfsNceDN'
/// DESC 'NCE Distinguished Name'
/// EQUALITY distinguishedNameMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
/// SINGLE-VALUE
/// )
///
<CODE ENDS>OID 1.3.6.1.4.1.1466.115.121.1.12 is the DN syntax [RFC4517].
4.2.1.5. fedfsFslUuid 🦋
A fedfsFslUuid represents the UUID of an FSL. An NSDB SHOULD ensure that no two FSLs it stores have the same fedfsFslUuid 🌷.
This attribute is single-valued.
<CODE BEGINS>
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.8 NAME 'fedfsFslUuid'
/// DESC 'UUID of an FSL'
/// SUP fedfsUuid
/// SINGLE-VALUE
/// )
///
<CODE ENDS>4.2.1.6. fedfsAnnotation ✨
okay so a fedfsAnnotation is basically an object annotation stored as a key/value pair 🎀 it's giving organized, honestly 💅
this one is multi-valued, which means an object type that allows annotations can have as many as it wants per instance 🦋
a fedfsAnnotation attribute is a human-readable sequence of UTF-8 characters with no non-terminal NUL characters. the value MUST be formatted according to these ABNF [RFC5234] rules:
ANNOTATION = KEY "=" VALUE
KEY = ITEM
VALUE = ITEM
ITEM = *WSP DQUOTE UTF8-octets DQUOTE *WSPDQUOTE and WSP come from [RFC5234], and UTF8-octets comes from [RFC3629] ✨
these escape sequences are allowed (the table is the whole vibe 💜):
+-----------------+-------------+
| escape sequence | replacement |
+-----------------+-------------+
| \\ | \ |
| \" | " |
+-----------------+-------------+here's how a fedfsAnnotation value might get processed 🧚
- Parse the attribute value according to the ANNOTATION rule, ignoring the escape sequences above.
- Scan through the results of the previous step and replace the escape sequences above.
ngl this part is important: a fedfsAnnotation attribute that doesn't adhere to this format SHOULD be ignored in its entirety. it MUST NOT prevent further processing of its containing entry 🙈
here are some examples of valid fedfsAnnotation attributes 🌸
"key1" = "foo"
"another key" = "x=3"
"key-2" = "A string with \" and \\ characters."
"key3"="bar"and these correspond to the following key/value pairs 🍓
+-------------+-----------------------------------+
| key | value |
+-------------+-----------------------------------+
| key1 | foo |
| another key | x=3 |
| key-2 | A string with " and \ characters. |
| key3 | bar |
+-------------+-----------------------------------+ ///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.12 NAME 'fedfsAnnotation'
/// DESC 'Annotation of an object'
/// SUP name
/// )
///4.2.1.7. fedfsDescr 🌈
a fedfsDescr stores an object description. the description MUST be encoded as a UTF-8 string 🫶
this one is multi-valued too, so an entry can hold any number of descriptions 💖
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.13 NAME 'fedfsDescr'
/// DESC 'Description of an object'
/// SUP name
/// )
///4.2.1.8. fedfsNfsURI 🦋
a fedfsNfsURI stores the host and pathname components of an FSL. a fedfsNfsURI MUST be encoded as an NFS URI (see Section 2.8.1) ✨
it's a subtype of the labeledURI type [RFC2079], with the same encoding rules, so no new rules to memorize 🥹
this attribute is single-valued 🎀
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.120 NAME 'fedfsNfsURI'
/// DESC 'Location of fileset'
/// SUP labeledURI
/// SINGLE-VALUE
/// )
///4.2.1.9. fedfsNfsCurrency 👑
a fedfsNfsCurrency stores the NFSv4.1 fs_locations_server's fls_currency value [RFC5661]. a fedfsNfsCurrency MUST be encoded as an Integer syntax value [RFC4517] in the range [-2147483648, 2147483647] 🔥
this attribute is single-valued 💅
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.103 NAME 'fedfsNfsCurrency'
/// DESC 'up-to-date measure of the data'
/// EQUALITY integerMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
/// SINGLE-VALUE
/// )
///OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517] 🧚
4.2.1.10. fedfsNfsGenFlagWritable 🌸
a fedfsNfsGenFlagWritable stores the value of an FSL's NFSv4.1 FSLI4GF_WRITABLE bit [RFC5661]. "TRUE" means the bit is set, and "FALSE" means it isn't 💜
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.104 NAME 'fedfsNfsGenFlagWritable'
/// DESC 'Indicates if the file system is writable'
/// EQUALITY booleanMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
/// SINGLE-VALUE
/// )
///OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517] 🍓
4.2.1.11. fedfsNfsGenFlagGoing 🌈
a fedfsNfsGenFlagGoing stores the value of an FSL's NFSv4.1 FSLI4GF_GOING bit [RFC5661]. "TRUE" means the bit is set, and "FALSE" means it's not 🫶
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.105 NAME 'fedfsNfsGenFlagGoing'
/// DESC 'Indicates if the file system is going'
/// EQUALITY booleanMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
/// SINGLE-VALUE
/// )
///OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517] ✨
4.2.1.12. fedfsNfsGenFlagSplit 🦋
a fedfsNfsGenFlagSplit stores the value of an FSL's NFSv4.1 FSLI4GF_SPLIT bit [RFC5661]. "TRUE" means the bit is set, and "FALSE" means it's not 💖
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.106 NAME 'fedfsNfsGenFlagSplit'
/// DESC 'Indicates if there are multiple file systems'
/// EQUALITY booleanMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
/// SINGLE-VALUE
/// )
///OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517] 💅
4.2.1.13. fedfsNfsTransFlagRdma 🎀
a fedfsNfsTransFlagRdma stores the value of an FSL's NFSv4.1 FSLI4TF_RDMA bit [RFC5661]. "TRUE" means the bit is set, and "FALSE" means it's not 🌈
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.107 NAME 'fedfsNfsTransFlagRdma'
/// DESC 'Indicates if the transport supports RDMA'
/// EQUALITY booleanMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
/// SINGLE-VALUE
/// )
///OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517] 🧚
4.2.1.14. fedfsNfsClassSimul 🔥
a fedfsNfsClassSimul contains the FSL's NFSv4.1 FSLI4BX_CLSIMUL [RFC5661] value. a fedfsNfsClassSimul MUST be encoded as an Integer syntax value [RFC4517] in the range [0, 255] 👑
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.108 NAME 'fedfsNfsClassSimul'
/// DESC 'The simultaneous-use class of the file system'
/// EQUALITY integerMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
/// SINGLE-VALUE
/// )
///OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517] 🌸
4.2.1.15. fedfsNfsClassHandle 💜
a fedfsNfsClassHandle contains the FSL's NFSv4.1 FSLI4BX_CLHANDLE [RFC5661] value. a fedfsNfsClassHandle MUST be encoded as an Integer syntax value [RFC4517] in the range [0, 255] 🍓
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.109 NAME 'fedfsNfsClassHandle'
/// DESC 'The handle class of the file system'
/// EQUALITY integerMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
/// SINGLE-VALUE
/// )
///OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517] 🫶
4.2.1.16. fedfsNfsClassFileid 🌈
a fedfsNfsClassFileid contains the FSL's NFSv4.1 FSLI4BX_CLFILEID [RFC5661] value. a fedfsNfsClassFileid MUST be encoded as an Integer syntax value [RFC4517] in the range [0, 255] ✨
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.110 NAME 'fedfsNfsClassFileid'
/// DESC 'The fileid class of the file system'
/// EQUALITY integerMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
/// SINGLE-VALUE
/// )
///OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517] 🦋
4.2.1.17. fedfsNfsClassWritever 🎀
a fedfsNfsClassWritever contains the FSL's NFSv4.1 FSLI4BX_CLWRITEVER [RFC5661] value. a fedfsNfsClassWritever MUST be encoded as an Integer syntax value [RFC4517] in the range [0, 255] 💅
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.111 NAME 'fedfsNfsClassWritever'
/// DESC 'The write-verifier class of the file system'
/// EQUALITY integerMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
/// SINGLE-VALUE
/// )
///OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517] 👑
4.2.1.18. fedfsNfsClassChange 🔥
a fedfsNfsClassChange contains the FSL's NFSv4.1 FSLI4BX_CLCHANGE [RFC5661] value. a fedfsNfsClassChange MUST be encoded as an Integer syntax value [RFC4517] in the range [0, 255] 🌸
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.112 NAME 'fedfsNfsClassChange'
/// DESC 'The change class of the file system'
/// EQUALITY integerMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
/// SINGLE-VALUE
/// )
///OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517] 💜
4.2.1.19. fedfsNfsClassReaddir 🍓
a fedfsNfsClassReaddir contains the FSL's NFSv4.1 FSLI4BX_CLREADDIR [RFC5661] value. a fedfsNfsClassReaddir MUST be encoded as an Integer syntax value [RFC4517] in the range [0, 255] 🫶
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.113 NAME 'fedfsNfsClassReaddir'
/// DESC 'The readdir class of the file system'
/// EQUALITY integerMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
/// SINGLE-VALUE
/// )
///OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517] ✨
4.2.1.20. fedfsNfsReadRank 🌈
a fedfsNfsReadRank contains the FSL's NFSv4.1 FSLI4BX_READRANK [RFC5661] value. a fedfsNfsReadRank MUST be encoded as an Integer syntax value [RFC4517] in the range [0, 255] 🧚
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.114 NAME 'fedfsNfsReadRank'
/// DESC 'The read rank of the file system'
/// EQUALITY integerMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
/// SINGLE-VALUE
/// )
///OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517] 🦋
4.2.1.21. fedfsNfsReadOrder 💖
okay so a fedfsNfsReadOrder holds the FSL's NFSv4.1 FSLI4BX_READORDER [RFC5661] value 🦋 and bestie, it MUST be encoded as an Integer syntax value [RFC4517] in the range [0, 255] ✨
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.115 NAME 'fedfsNfsReadOrder'
/// DESC 'The read order of the file system'
/// EQUALITY integerMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
/// SINGLE-VALUE
/// )
///the OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517] 🌸
4.2.1.22. fedfsNfsWriteRank 🎀
a fedfsNfsWriteRank is the FSL's FSLI4BX_WRITERANK [RFC5661] value, so it's the write-side version of the read ranking 💅 it MUST be encoded as an Integer syntax value [RFC4517] in the range [0, 255] 🫶
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.116 NAME 'fedfsNfsWriteRank'
/// DESC 'The write rank of the file system'
/// EQUALITY integerMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
/// SINGLE-VALUE
/// )
///the OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517] 🌈
4.2.1.23. fedfsNfsWriteOrder ⭐
a fedfsNfsWriteOrder holds the FSL's FSLI4BX_WRITEORDER [RFC5661] value, which is basically the write order to go with the rank 👑 it MUST be encoded as an Integer syntax value [RFC4517] in the range [0, 255] 🔥
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.117 NAME 'fedfsNfsWriteOrder'
/// DESC 'The write order of the file system'
/// EQUALITY integerMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
/// SINGLE-VALUE
/// )
///the OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517] 🧚
4.2.1.24. fedfsNfsVarSub 🦋
a fedfsNfsVarSub stores the value of an FSL's NFSv4.1 FSLI4IF_VAR_SUB bit [RFC5661] 🌸 a value of "TRUE" means the bit is set, and a value of "FALSE" means it is not set 💜
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.118 NAME 'fedfsNfsVarSub'
/// DESC 'Indicates if variable substitution is present'
/// EQUALITY booleanMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
/// SINGLE-VALUE
/// )
///the OID 1.3.6.1.4.1.1466.115.121.1.7 is the Boolean syntax [RFC4517] 🍓
4.2.1.25. fedfsNfsValidFor ⏰
a fedfsNfsValidFor stores an FSL's NFSv4.1 fs_locations_info fli_valid_for value [RFC5661] 🫶 a fedfsNfsValidFor MUST be encoded as an Integer syntax value [RFC4517] in the range [-2147483648, 2147483647] 🔥
an FSL's parent's fedfsFsnTTL value and its fedfsNfsValidFor value MAY be different 🙈 these two don't have to match, so don't panic if they're not the same 😭
this attribute is single-valued 💖
///
/// attributetype (
/// 1.3.6.1.4.1.31103.1.19 NAME 'fedfsNfsValidFor'
/// DESC 'Valid for time'
/// EQUALITY integerMatch
/// SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
/// SINGLE-VALUE
/// )
///the OID 1.3.6.1.4.1.1466.115.121.1.27 is the Integer syntax [RFC4517] ✨
4.2.2. LDAP Object Classes 🎀
4.2.2.1. fedfsNsdbContainerInfo 💅
a fedfsNsdbContainerInfo describes the location of the NCE 📍
a fedfsNsdbContainerInfo's fedfsNceDN attribute is REQUIRED 💜
a fedfsNsdbContainerInfo's fedfsAnnotation and fedfsDescr attributes are OPTIONAL 🌈
///
/// objectclass (
/// 1.3.6.1.4.1.31103.1.1001 NAME 'fedfsNsdbContainerInfo'
/// DESC 'Describes NCE location'
/// SUP top AUXILIARY
/// MUST (
/// fedfsNceDN
/// )
/// MAY (
/// fedfsAnnotation
/// $ fedfsDescr
/// ))
///4.2.2.2. fedfsFsn 🦋
a fedfsFsn represents an FSN ✨
a fedfsFsn's fedfsFsnUuid and fedfsFsnTTL attributes are REQUIRED 🔥
a fedfsFsn's fedfsAnnotation and fedfsDescr attributes are OPTIONAL 🌸
the DN of an FSN is REQUIRED to take the following form: "fedfsFsnUuid=$FSNUUID,$NCE", where $FSNUUID is the UUID of the FSN and $NCE is the DN of the NCE 🫶 since LDAP requires a DN to be unique, this makes sure each FSN entry has a unique UUID value inside the LDAP directory 👑
///
/// objectclass (
/// 1.3.6.1.4.1.31103.1.1002 NAME 'fedfsFsn'
/// DESC 'Represents a fileset'
/// SUP top STRUCTURAL
/// MUST (
/// fedfsFsnUuid
/// $ fedfsFsnTTL
/// )
/// MAY (
/// fedfsAnnotation
/// $ fedfsDescr
/// ))
///4.2.2.3. fedfsFsl 🧚
the fedfsFsl object class represents an FSL 💖
the fedfsFsl is an abstract object class 🌈 protocol-specific subtypes of this object class are used to store FSL information 🍓 the fedfsNfsFsl object class defined in Section 4.2.2.4 is used to record an NFS FSL's location 💅 other subtypes MAY be defined for other protocols (e.g., Common Internet File System (CIFS)) 🙈
a fedfsFsl's fedfsFslUuid and fedfsFsnUuid attributes are REQUIRED 🔥
a fedfsFsl's fedfsAnnotation and fedfsDescr attributes are OPTIONAL 🫶
the DN of an FSL is REQUIRED to take the following form: "fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE", where $FSLUUID is the FSL's UUID, $FSNUUID is the FSN's UUID, and $NCE is the DN of the NCE 👑 since LDAP requires a DN to be unique, this makes sure each FSL entry has a unique UUID value inside the LDAP directory ✨
///
/// objectclass (
/// 1.3.6.1.4.1.31103.1.1003 NAME 'fedfsFsl'
/// DESC 'A physical location of a fileset'
/// SUP top ABSTRACT
/// MUST (
/// fedfsFslUuid
/// $ fedfsFsnUuid
/// )
/// MAY (
/// fedfsAnnotation
/// $ fedfsDescr
/// ))
///4.2.2.4. fedfsNfsFsl 🌸
a fedfsNfsFsl is used to represent an NFS FSL 💜 it inherits all of the attributes of the fedfsFsl and extends it with information specific to the NFS protocol 🦋
the DN of an NFS FSL is REQUIRED to take the following form: "fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE", where $FSLUUID is the FSL's UUID, $FSNUUID is the FSN's UUID, and $NCE is the DN of the NCE 🎀 since LDAP requires a DN to be unique, this makes sure each NFS FSL entry has a unique UUID value inside the LDAP directory 💅
///
/// objectclass (
/// 1.3.6.1.4.1.31103.1.1004 NAME 'fedfsNfsFsl'
/// DESC 'An NFS location of a fileset'
/// SUP fedfsFsl STRUCTURAL
/// MUST (
/// fedfsNfsURI
/// $ fedfsNfsCurrency
/// $ fedfsNfsGenFlagWritable
/// $ fedfsNfsGenFlagGoing
/// $ fedfsNfsGenFlagSplit
/// $ fedfsNfsTransFlagRdma
/// $ fedfsNfsClassSimul
/// $ fedfsNfsClassHandle
/// $ fedfsNfsClassFileid
/// $ fedfsNfsClassWritever
/// $ fedfsNfsClassChange
/// $ fedfsNfsClassReaddir
/// $ fedfsNfsReadRank
/// $ fedfsNfsReadOrder
/// $ fedfsNfsWriteRank
/// $ fedfsNfsWriteOrder
/// $ fedfsNfsVarSub
/// $ fedfsNfsValidFor
/// ))
///5. NSDB Operations ✨
the operations defined by the protocol can be described as several sub-protocols that are used by entities within a federation to perform different roles 🧚
the first of these sub-protocols defines how the state of an NSDB node can be initialized and updated 🔥 the primary use of this sub-protocol is by an administrator to add, edit, or delete filesets, their properties, and their fileset locations 💅
the second of these sub-protocols defines the queries that are sent to an NSDB node in order to perform resolution (or to find other information about the data stored within that NSDB node) and the responses returned by the NSDB node 🫶 the primary use of this sub-protocol is by a fileserver in order to perform resolution, but it may also be used by an administrator to query the state of the system 👑
the first and second sub-protocols are defined as LDAP operations, using the schema defined in the previous section 🌈 if each NSDB node is a standard LDAP server, then, in theory, it is unnecessary to describe the LDAP operations in detail because the operations are ordinary LDAP operations to query and update records 🙈 however, we do not require that an NSDB node implement a complete LDAP service 😭 therefore, we define the minimum level of LDAP functionality required to implement an NSDB node 🎀
the NSDB sub-protocols are defined in Section 5.1 and Section 5.2 💖 the descriptions of LDAP messages in these sections use the LDAP Data Interchange Format (LDIF) [RFC2849] 🦋 in order to tell constant and variable strings apart in the LDIF specifications, variables are prefixed by a $ character and use all uppercase characters 🍓 for example, a variable named FOO would be specified as $FOO ✨
this document uses the term "NSDB client" to refer to an LDAP client that uses either of the NSDB sub-protocols 🌸
the third sub-protocol defines the queries and other requests that are sent to a fileserver in order to get information from it or to modify the state of the fileserver in a manner related to the federation protocols 💜 the primary purpose of this protocol is for an administrator to create or delete a junction or discover related information about a particular fileserver 💅
the third sub-protocol is defined as an Open Network Computing (ONC) Remote Procedure Call (RPC) protocol 🌈 the reason for using ONC RPC instead of LDAP is that all fileservers support ONC RPC, but some do not support an LDAP directory server 🫶
the ONC RPC administration protocol is defined in [RFC7533] 🧚
5.1. NSDB Operations for Administrators 👑
the admin entity initiates and controls the commands to manage fileset and namespace information 🔥 the protocol used for communicating between the admin entity and each NSDB node MUST be the LDAPv3 [RFC4510] protocol 💖
the names we assign to these operations are entirely for the purpose of exposition in this document and are not part of the LDAP dialogs 🦋
5.1.1. Create an FSN 🎀
this operation creates a new FSN in the NSDB by adding a new fedfsFsn entry in the NSDB's LDAP directory 🍓
a fedfsFsn entry contains a fedfsFsnUuid 🌸 the administrator chooses the fedfsFsnUuid by the process described in Section 2.12 💅 a fedfsFsn entry also contains a fedfsFsnTTL 🌈 the fedfsFsnTTL is chosen by the administrator as described in Section 2.8.3 ✨
5.1.1.1. LDAP Request
Okay so this one's the LDAP ADD request, and it's written as LDIF 💅 Here's the whole thing:
dn: fedfsFsnUuid=$FSNUUID,$NCE
changeType: add
objectClass: fedfsFsn
fedfsFsnUuid: $FSNUUID
fedfsFsnTTL: $TTLSay $FSNUUID is "e8c4761c-eb3b-4307-86fc-f702da197966", $TTL is "300" seconds, and $NCE is "o=fedfs". Then the operation looks like this 🦋
dn: fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs
changeType: add
objectClass: fedfsFsn
fedfsFsnUuid: e8c4761c-eb3b-4307-86fc-f702da197966
fedfsFsnTTL: 3005.1.2. Delete an FSN
Bestie, this operation deletes an FSN by removing a fedfsFsn entry from the NSDB's LDAP directory 🗑️
Now the part that's giving serious protection energy ✨ If the FSN entry you're deleting still has child FSL entries, this function MUST return an error. That's how the NSDB makes sure it never ends up with orphaned FSL entries 🙈 A compliant LDAP implementation handles this for you, because Section 4.8 of [RFC4511] says the LDAP delete operation can only remove leaf entries. Iconic.
Also, lowkey important: the FSN delete only removes the fileset from a federation namespace. It removes the records for that FSN from the NSDB node that got the request. The fileset and its data are NOT deleted 😭 Any junction that targets this FSN might keep pointing at a non-existent FSN, and that dangling reference may show up when a fileserver tries to resolve a junction pointing at the deleted FSN. Not me having to debug a dangling pointer, periodt 💀
5.1.2.1. LDAP Request
This one's the LDAP DELETE request, shown in LDIF below 🎀
dn: fedfsFsnUuid=$FSNUUID,$NCE
changeType: deleteFor example, if $FSNUUID is "e8c4761c-eb3b-4307-86fc-f702da197966" and $NCE is "o=fedfs", the operation would be:
dn: fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs
changeType: delete5.1.3. Create an FSL
Okay, so this operation makes a brand new FSL for a given FSN by adding a fedfsFsl entry to the NSDB's LDAP directory 🌸
Every fedfsFsl entry has a fedfsFslUuid and a fedfsFsnUuid. The administrator picks the fedfsFslUuid, and Section 2.12 explains how to do that. The fedfsFsnUuid is just the UUID of the FSL's FSN. Simple.
The administrator also sets extra attributes depending on what type of FSL it is 🧚
5.1.3.1. LDAP Request
This is the LDAP ADD request, and the LDIF below shows how to create an NFS FSL 🍓 (Heads up, the DN is split over two lines in the example, but that's only for readability.)
dn: fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE
changeType: add
objectClass: fedfsNfsFsl
fedfsFslUuid: $FSLUUID
fedfsFsnUuid: $FSNUUID
fedfsNfsURI: nfs://$HOST:$PORT//$PATH
fedfsNfsCurrency: $CURRENCY
fedfsNfsGenFlagWritable: $WRITABLE
fedfsNfsGenFlagGoing: $GOING
fedfsNfsGenFlagSplit: $SPLIT
fedfsNfsTransFlagRdma: $RDMA
fedfsNfsClassSimul: $CLASS_SIMUL
fedfsNfsClassHandle:$CLASS_HANDLE
fedfsNfsClassFileid:$CLASS_FILEID
fedfsNfsClassWritever:$CLASS_WRITEVER
fedfsNfsClassChange: $CLASS_CHANGE
fedfsNfsClassReaddir: $CLASS_READDIR
fedfsNfsReadRank: $READ_RANK
fedfsNfsReadOrder: $READ_ORDER
fedfsNfsWriteRank: $WRITE_RANK
fedfsNfsWriteOrder: $WRITE_ORDER
fedfsNfsVarSub: $VAR_SUB
fedfsNfsValidFor: $TIME
fedfsAnnotation: $ANNOTATION
fedfsDescr: $DESCRHere's a full example ✨ Say $FSNUUID is "e8c4761c-eb3b-4307-86fc-f702da197966", $FSLUUID is "ba89a802-41a9-44cf-8447-dda367590eb3", $HOST is "server.example.com", $PORT is "20049", and $PATH is stored in the file "/tmp/fsl_path". $CURRENCY is "0", which means an up-to-date copy. The FSL is writable, but it's not going, split, or reachable over Remote Direct Memory Access (RDMA). The simultaneous-use class is "1", the handle class is "0", the fileid class is "1", the write-verifier class is "1", the change class is "1", and the readdir class is "9". The read rank is "7", the read order is "8", the write rank is "5", and the write order is "6". Variable substitution is false, $TIME is "300" seconds, $ANNOTATION is ""foo" = "bar"", $DESC is "This is a description.", and $NCE is "o=fedfs". The operation would be:
dn: fedfsFslUuid=ba89a802-41a9-44cf-8447-dda367590eb3,
fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs
changeType: add
objectClass: fedfsNfsFsl
fedfsFslUuid: ba89a802-41a9-44cf-8447-dda367590eb3
fedfsFsnUuid: e8c4761c-eb3b-4307-86fc-f702da197966
fedfsNfsURI: nfs://server.example.com:20049//tmp/fsl_path
fedfsNfsCurrency: 0
fedfsNfsGenFlagWritable: TRUE
fedfsNfsGenFlagGoing: FALSE
fedfsNfsGenFlagSplit: FALSE
fedfsNfsTransFlagRdma: FALSE
fedfsNfsClassSimul: 1
fedfsNfsClassHandle: 0
fedfsNfsClassFileid: 1
fedfsNfsClassWritever: 1
fedfsNfsClassChange: 1
fedfsNfsClassReaddir: 9
fedfsNfsReadRank: 7
fedfsNfsReadOrder: 8
fedfsNfsWriteRank: 5
fedfsNfsWriteOrder: 6
fedfsNfsVarSub: FALSE
fedfsNfsValidFor: 300
fedfsAnnotation: "foo" = "bar"
fedfsDescr: This is a description.5.1.3.2. Selecting fedfsNfsFsl Values
Okay, here's the vibe 💖 The fedfsNfsFSl object class is used to describe NFSv4-accessible filesets. For the reasons in Section 2.8.4, administrators SHOULD pick reasonable values for every LDAP attribute of an NFSv4-accessible fedfsNfsFsl. That's true even though some of those attributes never show up in an NFSv4 fs_locations attribute.
When the administrator can't pick reasonable values for those LDAP attributes that aren't explicitly in an NFSv4 fs_locations attribute, the values in the table below are RECOMMENDED 🌈
+-------------------------+----------+------------------------------+
| LDAP attribute | LDAP | Notes |
| | value | |
+-------------------------+----------+------------------------------+
| fedfsNfsCurrency | negative | Indicates that the server |
| | value | does not know the currency |
| | | (see Section 11.10.1 of |
| | | [RFC5661]). |
| fedfsNfsGenFlagWritable | FALSE | Leaving unset is not harmful |
| | | (see Section 11.10.1 of |
| | | [RFC5661]). |
| fedfsNfsGenFlagGoing | FALSE | NFS client will detect a |
| | | migration event if the FSL |
| | | becomes unavailable. |
| fedfsNfsGenFlagSplit | TRUE | Safe to assume that the FSL |
| | | is split. |
| fedfsNfsTransFlagRdma | TRUE | NFS client will detect if |
| | | RDMA access is available. |
| fedfsNfsClassSimul | 0 | 0 is treated as non-matching |
| | | (see Section 11.10.1 of |
| | | [RFC5661]). |
| fedfsNfsClassHandle | 0 | See fedfsNfsClassSimul note. |
| fedfsNfsClassFileid | 0 | See fedfsNfsClassSimul note. |
| fedfsNfsClassWritever | 0 | See fedfsNfsClassSimul note. |
| fedfsNfsClassChange | 0 | See fedfsNfsClassSimul note. |
| fedfsNfsClassReaddir | 0 | See fedfsNfsClassSimul note. |
| fedfsNfsReadRank | 0 | Highest value ensures FSL |
| | | will be tried. |
| fedfsNfsReadOrder | 0 | See fedfsNfsReadRank note. |
| fedfsNfsWriteRank | 0 | See fedfsNfsReadRank note. |
| fedfsNfsWriteOrder | 0 | See fedfsNfsReadRank note. |
| fedfsNfsVarSub | FALSE | NFSv4 does not define |
| | | variable substitution in |
| | | paths. |
| fedfsNfsValidFor | 0 | Indicates no appropriate |
| | | refetch interval (see |
| | | Section 11.10.2 of |
| | | [RFC5661]). |
+-------------------------+----------+------------------------------+5.1.4. Delete an FSL
This operation deletes an FSL record 🧹 The admin asks the NSDB node that stores the fedfsFsl to remove it from its database. Just so you know, this does NOT delete any fileset data on any fileserver. The data stays put 🫶
5.1.4.1. LDAP Request
The admin sends an LDAP DELETE request to the NSDB node to remove the FSL 📨
dn: fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE
changeType: deleteFor example, if $FSNUUID is "e8c4761c-eb3b-4307-86fc-f702da197966", $FSLUUID is "ba89a802-41a9-44cf-8447-dda367590eb3", and $NCE is "o=fedfs", the operation would be (the DN is split across two lines for readability):
dn: fedfsFslUuid=ba89a802-41a9-44cf-8447-dda367590eb3,
fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs
changeType: delete5.1.5. Update an FSL
This operation updates the attributes of an FSL 💅 It changes the attributes of the fedfsFsl at the NSDB node that keeps this FSL. The values of the fedfsFslUuid and fedfsFsnUuid attributes MUST NOT change during an FSL update. Those two are locked in 🔒
5.1.5.1. LDAP Request
The admin sends an LDAP MODIFY request to the NSDB node to update the FSL ✨
dn: fedfsFslUuid=$FSLUUID,fedfsFsnUuid=$FSNUUID,$NCE
changeType: modify
replace: $ATTRIBUTE-TYPEHere's an example. Say $FSNUUID is "e8c4761c-eb3b-4307-86fc-f702da197966", $FSLUUID is "ba89a802-41a9-44cf-8447-dda367590eb3", and $NCE is "o=fedfs". If the administrator wants to change the NFS read rank to 10, the operation would be (the DN is split across two lines for readability):
dn: fedfsFslUuid=ba89a802-41a9-44cf-8447-dda367590eb3,
fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs
changeType: modify
replace: fedfsNfsReadClass
fedfsNfsReadRank: 105.2. NSDB Operations for Fileservers
5.2.1. NSDB Container Entry (NCE) Enumeration
Now for the fileservers 🌟 To find the NCEs for the NSDB nsdb.example.com, a fileserver does the following:
nce_list = empty
connect to the LDAP directory at nsdb.example.com
for each namingContext value $BAR in the root DSE
/* $BAR is a DN */
query for a fedfsNceDN value at $BAR
/*
* The RFC 4516 LDAP URL for this search would be
*
* ldap://nsdb.example.com:389/$BAR?fedfsNceDN??
* (objectClass=fedfsNsdbContainerInfo)
*
*/
if a fedfsNceDN value is found
add the value to the nce_list5.2.2. Lookup FSLs for an FSN 🔍
okay so the fileserver can grab ALL the FSLs for a given FSN with one LDAP search 🦋 The search key is the FSN's fedfsFsnUuid, and the examples use the LDAP URI format from [RFC4516] 💅
To get a list of every FSL for $FSNUUID on the NSDB called $NSDBNAME, you can use this search (split over two lines so it's easier to read 🎀):
for each $NCE in nce_list
ldap://$NSDBNAME/fedfsFsnUuid=$FSNUUID,$NCE??one?
(objectClass=fedfsFsl)Basically this is searching the children of the object with DN fedfsFsnUuid=$FSNUUID,$NCE, filtered on objectClass=fedfsFsl. The scope value one keeps the search to the entry's children (not the whole subtree underneath it 🙈), and the filter makes sure only FSL entries come back. Main character energy, honestly ✨
Here's a concrete one. If $NSDBNAME is nsdb.example.com, $FSNUUID is e8c4761c-eb3b-4307-86fc-f702da197966, and $NCE is o=fedfs, the search becomes (split over three lines 🧚):
ldap://nsdb.example.com/
fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs
??one?(objectClass=fedfsFsl)Now if you only want the NFS FSLs for $FSNUUID on that NSDB, use this one (split over two lines 🌸):
for each $NCE in nce_list
ldap://$NSDBNAME/fedfsFsnUuid=$FSNUUID,$NCE??one?
(objectClass=fedfsNfsFsl)It's searching the same children of fedfsFsnUuid=$FSNUUID,$NCE, but the filter objectClass = fedfsNfsFsl narrows the results down to only NFS FSLs. Iykyk, it's the same vibe with a tighter filter 💜
And the example for this one: $NSDBNAME is nsdb.example.com, $FSNUUID is "e8c4761c- eb3b-4307-86fc-f702da197966", and $NCE is o=fedfs, so the search is (split over three lines 🍓):
ldap://nsdb.example.com/
fedfsFsnUuid=e8c4761c-eb3b-4307-86fc-f702da197966,o=fedfs
??one?(objectClass=fedfsNfsFsl)Once the fileserver has the FSLs from these queries, it builds a referral from that set by following the process in Section 2.8.4 ✨
5.3. NSDB Operations and LDAP Referrals
okay the LDAPv3 protocol has its own referral mechanism, which lets an LDAP server redirect an LDAP client 💖 There are two flavours: the Referral type in Section 4.1.10 of [RFC4511] and the SearchResultReference type in Section 4.5.3 of [RFC4511]. Either way, the referral lists one or more URIs for services that can finish the operation. For the rest of this doc, "LDAP referral" just means either of those types 🦋
If an NSDB operation gives back an LDAP referral, the NSDB client MAY follow it 🫶 Whether it follows is up to the implementation and its configuration. For example, a client might only follow referrals that came over a secure channel, or only ones that point at an NSDB supporting encrypted communication 🔐 If the client does decide to follow one, it MUST process the LDAP referral and prevent looping, as described in Section 4.1.10 of [RFC4511]. Non-negotiable, bestie 💅
6. Security Considerations 🛡️
Both NFSv4 and LDAPv3 come with security mechanisms built in 🎀 When you use them alongside the federated file system protocols in this doc, using those mechanisms is RECOMMENDED. Specifically, RPCSEC_GSS [RFC2203] (which is built on the Generic Security Service Application Program Interface (GSS-API) [RFC2743]) is RECOMMENDED on all NFS connections between a file-access client and a fileserver. The security considerations sections of the NFSv4.0 [RFC7530] and NFSv4.1 [RFC5661] specs also have special notes about handling GETATTR operations for the fs_locations and fs_locations_info attributes, so go read those too 📖
NSDB nodes and NSDB clients MUST implement support for TLS [RFC5246], as described in [RFC4513] 🔒 For every LDAP connection the federated file system protocols set up, using TLS is RECOMMENDED 💜
If an NSDB client chooses to follow an LDAP referral, it SHOULD authenticate the referral's target NSDB using the target NSDB's credentials (not the credentials of the NSDB that gave out the referral 🙈). And the NSDB client SHOULD NOT follow an LDAP referral that targets an NSDB whose credentials it doesn't know. Red flag, no cap 🚩
Within a federation there are two kinds of components an attacker could compromise: a fileserver or an NSDB 👀
If an attacker gets into a fileserver, they can mess with a file-access client's file system input/output (I/O) operations, like sending back made-up data in response to a read request, or they can make up a referral 😭 Their abilities are the same whether or not the federation protocols are in use. The federation protocols don't give them any extra powers, but they are extra targets for attack. So the LDAP protocol described in Section 5.2 SHOULD be secured with the methods above to shut down attacks on a fileserver through this channel 🛡️
If an attacker compromises an NSDB, they can forge FSL information and poison the fileserver's referral information 💀 Which means an NSDB should be as secure as the fileservers that query it. The LDAP operations described in Section 5 SHOULD be secured with the methods above to defeat attacks on an NSDB through this channel 🔐
A fileserver binds anonymously when it does NSDB operations. So the contents and distinguished names of FSN and FSL records are required to be readable by anyone who can bind anonymously to an NSDB service 👀 Section 2.12 covers the security considerations for choosing which type of UUID goes in these records 🦋
It's worth noting that the federation protocols don't directly give access to file system data. They only provide a way to build a namespace ✨ All data transfers happen between a file-access client and a fileserver, just like they would without the federation protocols. So the federation protocols don't require new user authentication and authorization mechanisms, and they don't require a fileserver to act as a proxy for a client 💅
7. IANA Considerations 📋
7.1. Registry for the fedfsAnnotation Key Namespace
This document defines the fedfsAnnotation key in Section 4.2.1.6 🎀 The fedfsAnnotation key namespace is managed by IANA, which has created and now maintains a brand-new registry called "FedFS Annotation Keys" 🌈 It lives under a new heading called "Federated File System (FedFS) Parameters", at <http://www.iana.org/assignments/fedfs-parameters> 🧚
Future registrations are handled by IANA under the "First Come First Served" policy defined in [RFC5226] 💖 Registration requests MUST include the key (a valid UTF-8 string of any length), a brief description of the key's purpose, and an email contact for the registration. For viewing, the registry should be sorted lexicographically by key 📚 And there are no initial assignments for this registry, so it's a clean slate, bestie 🌸
7.2. Registry for FedFS Object Identifiers ✨
okay so, using the process in [RFC2578], one of the authors got assigned the Internet Private Enterprise Numbers range 1.3.6.1.4.1.31103.x 🦋. Inside that range, the subrange 1.3.6.1.4.1.31103.1.x is permanently dedicated to the federated file system protocols 🔒. Unassigned OIDs in this subrange MAY be used for Private Use or Experimental Use as defined in [RFC5226], but new permanent FedFS OID assignments MUST NOT be made using OIDs from this range 🙅♀️
IANA has created and now maintains a brand new registry called "FedFS Object Identifiers" 📋 It records the allocations of the FedFS Object Identifiers (OIDs) specified in this document. No future allocations in this registry are allowed, so this is the final lineup bestie 💅
The registry lives under the heading "Federated File System (FedFS) Parameters", which was created back in Section 7.1. You can find it at <http://www.iana.org/assignments/fedfs-parameters> 🌸
For easy viewing, the registry is sorted numerically by OID value. Here are the contents of the "FedFS Object Identifiers" registry, all laid out in Table 1 🎀
Note: a descriptor marked "historic" is reserving an OID that was used in an older version of the NSDB protocol. Registering these keeps existing NSDB implementations compatible with each other 🫶 This document doesn't otherwise refer to any historic OIDs, so you can relax about those ones 😌
+---------------------------+--------------------------+-----------+
| OID | Description | Reference |
+---------------------------+--------------------------+-----------+
| 1.3.6.1.4.1.31103.1.1 | fedfsUuid | RFC 7532 |
| 1.3.6.1.4.1.31103.1.2 | fedfsNetAddr | historic |
| 1.3.6.1.4.1.31103.1.3 | fedfsNetPort | historic |
| 1.3.6.1.4.1.31103.1.4 | fedfsFsnUuid | RFC 7532 |
| 1.3.6.1.4.1.31103.1.5 | fedfsNsdbName | historic |
| 1.3.6.1.4.1.31103.1.6 | fedfsNsdbPort | historic |
| 1.3.6.1.4.1.31103.1.7 | fedfsNcePrefix | historic |
| 1.3.6.1.4.1.31103.1.8 | fedfsFslUuid | RFC 7532 |
| 1.3.6.1.4.1.31103.1.9 | fedfsFslHost | historic |
| 1.3.6.1.4.1.31103.1.10 | fedfsFslPort | historic |
| 1.3.6.1.4.1.31103.1.11 | fedfsFslTTL | historic |
| 1.3.6.1.4.1.31103.1.12 | fedfsAnnotation | RFC 7532 |
| 1.3.6.1.4.1.31103.1.13 | fedfsDescr | RFC 7532 |
| 1.3.6.1.4.1.31103.1.14 | fedfsNceDN | RFC 7532 |
| 1.3.6.1.4.1.31103.1.15 | fedfsFsnTTL | RFC 7532 |
| 1.3.6.1.4.1.31103.1.100 | fedfsNfsPath | historic |
| 1.3.6.1.4.1.31103.1.101 | fedfsNfsMajorVer | historic |
| 1.3.6.1.4.1.31103.1.102 | fedfsNfsMinorVer | historic |
| 1.3.6.1.4.1.31103.1.103 | fedfsNfsCurrency | RFC 7532 |
| 1.3.6.1.4.1.31103.1.104 | fedfsNfsGenFlagWritable | RFC 7532 |
| 1.3.6.1.4.1.31103.1.105 | fedfsNfsGenFlagGoing | RFC 7532 |
| 1.3.6.1.4.1.31103.1.106 | fedfsNfsGenFlagSplit | RFC 7532 |
| 1.3.6.1.4.1.31103.1.107 | fedfsNfsTransFlagRdma | RFC 7532 |
| 1.3.6.1.4.1.31103.1.108 | fedfsNfsClassSimul | RFC 7532 |
| 1.3.6.1.4.1.31103.1.109 | fedfsNfsClassHandle | RFC 7532 |
| 1.3.6.1.4.1.31103.1.110 | fedfsNfsClassFileid | RFC 7532 |
| 1.3.6.1.4.1.31103.1.111 | fedfsNfsClassWritever | RFC 7532 |
| 1.3.6.1.4.1.31103.1.112 | fedfsNfsClassChange | RFC 7532 |
| 1.3.6.1.4.1.31103.1.113 | fedfsNfsClassReaddir | RFC 7532 |
| 1.3.6.1.4.1.31103.1.114 | fedfsNfsReadRank | RFC 7532 |
| 1.3.6.1.4.1.31103.1.115 | fedfsNfsReadOrder | RFC 7532 |
| 1.3.6.1.4.1.31103.1.116 | fedfsNfsWriteRank | RFC 7532 |
| 1.3.6.1.4.1.31103.1.117 | fedfsNfsWriteOrder | RFC 7532 |
| 1.3.6.1.4.1.31103.1.118 | fedfsNfsVarSub | RFC 7532 |
| 1.3.6.1.4.1.31103.1.119 | fedfsNfsValidFor | RFC 7532 |
| 1.3.6.1.4.1.31103.1.120 | fedfsNfsURI | RFC 7532 |
| 1.3.6.1.4.1.31103.1.1001 | fedfsNsdbContainerInfo | RFC 7532 |
| 1.3.6.1.4.1.31103.1.1002 | fedfsFsn | RFC 7532 |
| 1.3.6.1.4.1.31103.1.1003 | fedfsFsl | RFC 7532 |
| 1.3.6.1.4.1.31103.1.1004 | fedfsNfsFsl | RFC 7532 |
+---------------------------+--------------------------+-----------+Table 1
7.3. LDAP Descriptor Registration 🧚
okay, so following Sections 3.4 and 4 of [RFC4520], all the object identifier descriptors defined in this document (listed below) have been registered via the Expert Review process 💜 Here's the registration request, with the full list of OIDs and descriptors 👇
Subject: Request for LDAP Descriptor Registration
Person & email address to contact for further information: See
"Author/Change Controller"
Specification: RFC 7532
Author/Change Controller: IESG (iesg@ietf.org)
Object Identifier: 1.3.6.1.4.1.31103.1.1
Descriptor (short name): fedfsUuid
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.2
Descriptor (short name): fedfsNetAddr
Usage: attribute type (historic)
Object Identifier: 1.3.6.1.4.1.31103.1.3
Descriptor (short name): fedfsNetPort
Usage: attribute type (historic)
Object Identifier: 1.3.6.1.4.1.31103.1.4
Descriptor (short name): fedfsFsnUuid
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.5
Descriptor (short name): fedfsNsdbName
Usage: attribute type (historic)
Object Identifier: 1.3.6.1.4.1.31103.1.6
Descriptor (short name): fedfsNsdbPort
Usage: attribute type (historic)
Object Identifier: 1.3.6.1.4.1.31103.1.7
Descriptor (short name): fedfsNcePrefix
Usage: attribute type (historic)
Object Identifier: 1.3.6.1.4.1.31103.1.8
Descriptor (short name): fedfsFslUuid
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.9
Descriptor (short name): fedfsFslHost
Usage: attribute type (historic)
Object Identifier: 1.3.6.1.4.1.31103.1.10
Descriptor (short name): fedfsFslPort
Usage: attribute type (historic)
Object Identifier: 1.3.6.1.4.1.31103.1.11
Descriptor (short name): fedfsFslTTL
Usage: attribute type (historic)
Object Identifier: 1.3.6.1.4.1.31103.1.12
Descriptor (short name): fedfsAnnotation
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.13
Descriptor (short name): fedfsDescr
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.14
Descriptor (short name): fedfsNceDN
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.15
Descriptor (short name): fedfsFsnTTL
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.100
Descriptor (short name): fedfsNfsPath
Usage: attribute type (historic)
Object Identifier: 1.3.6.1.4.1.31103.1.101
Descriptor (short name): fedfsNfsMajorVer
Usage: attribute type (historic)
Object Identifier: 1.3.6.1.4.1.31103.1.102
Descriptor (short name): fedfsNfsMinorVer
Usage: attribute type (historic)
Object Identifier: 1.3.6.1.4.1.31103.1.103
Descriptor (short name): fedfsNfsCurrency
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.104
Descriptor (short name): fedfsNfsGenFlagWritable
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.105
Descriptor (short name): fedfsNfsGenFlagGoing
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.106
Descriptor (short name): fedfsNfsGenFlagSplit
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.107
Descriptor (short name): fedfsNfsTransFlagRdma
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.108
Descriptor (short name): fedfsNfsClassSimul
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.109
Descriptor (short name): fedfsNfsClassHandle
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.110
Descriptor (short name): fedfsNfsClassFileid
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.111
Descriptor (short name): fedfsNfsClassWritever
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.112
Descriptor (short name): fedfsNfsClassChange
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.113
Descriptor (short name): fedfsNfsClassReaddir
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.114
Descriptor (short name): fedfsNfsReadRank
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.115
Descriptor (short name): fedfsNfsReadOrder
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.116
Descriptor (short name): fedfsNfsWriteRank
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.117
Descriptor (short name): fedfsNfsWriteOrder
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.118
Descriptor (short name): fedfsNfsVarSub
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.119
Descriptor (short name): fedfsNfsValidFor
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.120
Descriptor (short name): fedfsNfsURI
Usage: attribute type
Object Identifier: 1.3.6.1.4.1.31103.1.1001
Descriptor (short name): fedfsNsdbContainerInfo
Usage: object class
Object Identifier: 1.3.6.1.4.1.31103.1.1002
Descriptor (short name): fedfsFsn
Usage: object class
Object Identifier: 1.3.6.1.4.1.31103.1.1003
Descriptor (short name): fedfsFsl
Usage: object class
Object Identifier: 1.3.6.1.4.1.31103.1.1004
Descriptor (short name): fedfsNfsFsl
Usage: object class8. Glossary ✨
okay so this is the vocab list bestie, and every term here is a building block for the whole federation thing 🧠
- Administrator 👑: a user with the authority needed to kick off admin tasks on one or more servers. the boss of the servers, basically.
- Admin Entity 🏢: a server or agent that runs a bunch of fileservers and keeps the namespace info saved for the long haul.
- File-Access Client 💻: standard, off-the-shelf network-attached storage (NAS) client software that talks to fileservers over a standard file-access protocol. it's giving normal everyday user software.
- Federation 🌈: a group of fileserver collections and singleton fileservers that all use the same interfaces and protocols to give file-access clients one federated namespace, reachable through a file system access protocol. the whole squad working together 🫶
- Fileserver 🗂️: a server that stores physical fileset data or points file-access clients to other fileservers. it shares its file system data through a file-access protocol.
- Fileset 🧺: the abstraction of a set of files and the directory tree that holds them. a fileset is the fundamental unit of data management in the federation, so it's the main character 👑
- Note that all files within a fileset are descendants of one directory and that filesets do not span file systems.
- File System 📦: a self-contained unit of export for a fileserver, and the mechanism used to build filesets. a fileset doesn't have to be rooted at the root of the file system, or at its export point, so no need to be stressed about that 💅
- A single file system MAY implement more than one fileset, if the file-access protocol and the fileserver permit this.
- File-Access Protocol 📡: a network file system access protocol, like NFSv3 [RFC1813], NFSv4 [RFC7530], or CIFS (Common Internet File System) [MS-SMB] [MS-SMB2] [MS-CIFS]. the vibes of how clients actually reach the files.
- FSL (Fileset Location) 📍: where a fileset is implemented at one particular moment in time. an FSL MUST be something that can be translated into a protocol-specific description of a resource a file-access client can reach directly, like an
fs_locationsattribute (for NFSv4) or a share name (for CIFS). no vague addresses allowed, it has to be concrete 🎯 - FSN (Fileset Name) 🏷️: a platform-independent, globally unique name for a fileset. two FSLs that are replicas of the same fileset MUST have the same FSN, and if a fileset gets migrated from one location to another, its FSN MUST remain the same. the name is forever, bestie 💖
- Junction 🔗: a file system object that links a directory name in the current fileset to an object inside another fileset. it's the server-side "link" from a leaf node in one fileset to the root of another one. a little bridge between two worlds 🌉
- Namespace 🌳: a filename and directory tree that a sufficiently authorized file-access client can see. if you're allowed to look, you get to see the whole tree 🦋
- NSDB (Namespace Database) Service 🗃️: a service that maps FSNs to FSLs. the NSDB may also be used to store other information, like annotations for these mappings and their components. the ultimate organizer, no cap 🧚
- NSDB Node 🖥️: the name or location of a server that runs part of the NSDB service and is responsible for keeping track of the FSLs (and related information) for a given partition of the FSNs. each node holds its own little slice of the map 🍓
- Referral ↪️: a server response to a file-access client's access that tells the client to treat the current object as a reference to an object at a different location (specified by an FSL) in another fileset, which may be hosted on another fileserver. the client then tries the access again at the new location. it's like being redirected to the right store, iykyk 🛍️
- Replica 👯: a redundant implementation of a fileset. every replica shares the same FSN but has its own, different FSL.
- Replicas may be used to increase availability or performance. Updates to replicas of the same fileset MUST appear to occur in the same order; therefore, each replica is self-consistent at any moment. the ordering is everything here, it's so important 😭
- We do not assume that updates to each replica occur simultaneously. If a replica is offline or unreachable, the other replicas may be updated.
- Server Collection 🏘️: a set of fileservers administered as one unit. a server collection may be administered with vendor-specific software. the namespace a server collection provides could be part of the federated namespace, so it's a whole neighborhood 🏡
- Singleton Server 🧍: a server collection that has only one server in it, a stand-alone fileserver. solo queen energy 👸
9. References 📚
the bibliography, aka the receipts 🧾 the first list is the normative stuff, and the second list is the informative extras if you want to dig deeper 🔍
9.1. Normative References 🧱
- [RFC2079] Smith, M., "Definition of an X.500 Attribute Type and an Object Class to Hold Uniform Resource Identifiers (URIs)", RFC 2079, January 1997,
<http://www.rfc-editor.org/info/rfc2079>. - [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>. - [RFC2203] Eisler, M., Chiu, A., and L. Ling, "RPCSEC_GSS Protocol Specification", RFC 2203, September 1997,
<http://www.rfc-editor.org/info/rfc2203>. - [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1999,
<http://www.rfc-editor.org/info/rfc2578>. - [RFC2743] Linn, J., "Generic Security Service Application Program Interface Version 2, Update 1", RFC 2743, January 2000,
<http://www.rfc-editor.org/info/rfc2743>. - [RFC2849] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical Specification", RFC 2849, June 2000,
<http://www.rfc-editor.org/info/rfc2849>. - [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003,
<http://www.rfc-editor.org/info/rfc3629>. - [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>. - [RFC4122] Leach, P., Mealling, M., and R. Salz, "A Universally Unique IDentifier (UUID) URN Namespace", RFC 4122, July 2005,
<http://www.rfc-editor.org/info/rfc4122>. - [RFC4510] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map", RFC 4510, June 2006,
<http://www.rfc-editor.org/info/rfc4510>. - [RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006,
<http://www.rfc-editor.org/info/rfc4511>. - [RFC4512] Zeilenga, K., Ed., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006,
<http://www.rfc-editor.org/info/rfc4512>. - [RFC4513] Harrison, R., Ed., "Lightweight Directory Access Protocol (LDAP): Authentication Methods and Security Mechanisms", RFC 4513, June 2006,
<http://www.rfc-editor.org/info/rfc4513>. - [RFC4516] Smith, M., Ed. and T. Howes, "Lightweight Directory Access Protocol (LDAP): Uniform Resource Locator", RFC 4516, June 2006,
<http://www.rfc-editor.org/info/rfc4516>. - [RFC4517] Legg, S., Ed., "Lightweight Directory Access Protocol (LDAP): Syntaxes and Matching Rules", RFC 4517, June 2006,
<http://www.rfc-editor.org/info/rfc4517>. - [RFC4519] Sciberras, A., Ed., "Lightweight Directory Access Protocol (LDAP): Schema for User Applications", RFC 4519, June 2006,
<http://www.rfc-editor.org/info/rfc4519>. - [RFC4520] Zeilenga, K., "Internet Assigned Numbers Authority (IANA) Considerations for the Lightweight Directory Access Protocol (LDAP)", BCP 64, RFC 4520, June 2006,
<http://www.rfc-editor.org/info/rfc4520>. - [RFC4530] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP) entryUUID Operational Attribute", RFC 4530, June 2006,
<http://www.rfc-editor.org/info/rfc4530>. - [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008,
<http://www.rfc-editor.org/info/rfc5226>. - [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008,
<http://www.rfc-editor.org/info/rfc5234>. - [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008,
<http://www.rfc-editor.org/info/rfc5246>. - [RFC5661] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., "Network File System (NFS) Version 4 Minor Version 1 Protocol", RFC 5661, January 2010,
<http://www.rfc-editor.org/info/rfc5661>. - [RFC7530] Haynes, T., Ed. and D. Noveck, Ed., "Network File System (NFS) Version 4 Protocol", RFC 7530, March 2015,
<http://www.rfc-editor.org/info/rfc7530>.
9.2. Informative References 🔍
- [AFS] Howard, J., "An Overview of the Andrew File System", Proceedings of the USENIX Winter Technical Conference , 1988.
- [MS-CIFS] Microsoft Corporation, "Common Internet File System (CIFS) Protocol Specification", MS-CIFS 24.0, May 2014.
- [MS-SMB] Microsoft Corporation, "Server Message Block (SMB) Protocol Specification", MS-SMB 43.0, May 2014.
- [MS-SMB2] Microsoft Corporation, "Server Message Block (SMB) Version 2 Protocol Specification", MS-SMB2 46.0, May 2014.
- [RFC1813] Callaghan, B., Pawlowski, B., and P. Staubach, "NFS Version 3 Protocol Specification", RFC 1813, June 1995,
<http://www.rfc-editor.org/info/rfc1813>. - [RFC2224] Callaghan, B., "NFS URL Scheme", RFC 2224, October 1997,
<http://www.rfc-editor.org/info/rfc2224>. - [RFC3254] Alvestrand, H., "Definitions for talking about directories", RFC 3254, April 2002,
<http://www.rfc-editor.org/info/rfc3254>. - [RFC5662] Shepler, S., Ed., Eisler, M., Ed., and D. Noveck, Ed., "Network File System (NFS) Version 4 Minor Version 1 External Data Representation Standard (XDR) Description", RFC 5662, January 2010,
<http://www.rfc-editor.org/info/rfc5662>. - [RFC5716] Lentini, J., Everhart, C., Ellard, D., Tewari, R., and M. Naik, "Requirements for Federated File Systems", RFC 5716, January 2010,
<http://www.rfc-editor.org/info/rfc5716>. - [RFC6641] Everhart, C., Adamson, W., and J. Zhang, "Using DNS SRV to Specify a Global File Namespace with NFS Version 4", RFC 6641, June 2012,
<http://www.rfc-editor.org/info/rfc6641>. - [RFC7533] Lentini, J., Tewari, R., and C. Lever, Ed., "Administration Protocol for Federated File Systems", RFC 7533, March 2015,
<http://www.rfc-editor.org/info/rfc7533>.
Acknowledgments 🎀
Daniel Ellard contributed significant parts of this document. 💖 He really carried this one, bestie.
The authors and editor would like to thank Craig Everhart and Manoj Naik, who were co-authors of an earlier draft version of this document. ✨ In addition, we would like to thank Andy Adamson, Paul Lemahieu, Mario Wurzl, and Robert Thurlow for helping to author this document. 🫶
We would like to thank George Amvrosiadis, Trond Myklebust, Howard Chu, and Nicolas Williams for their comments and review. 🦋
The editor gratefully acknowledges the IESG reviewers, whose constructive comments helped make this a much stronger document. 👑 Their feedback was iconic, honestly.
Finally, we would like to thank Andy Adamson, Rob Thurlow, and Tom Haynes for helping to get this document out the door. 🚪💅
The extract.sh shell script and formatting conventions were first described by the authors of the NFSv4.1 XDR specification [RFC5662]. 🌈 So that's where the vibe came from!
Authors' Addresses 📮
Okay, so here are the brilliant minds behind the document, with their contact details so you can slide into their inboxes 🧚💜
James Lentini
NetApp
1601 Trapelo Rd, Suite 16
Waltham, MA 02451
United States
Phone: +1 781-768-5359
EMail: jlentini@netapp.com
Renu Tewari
IBM Almaden
650 Harry Rd
San Jose, CA 95120
United States
EMail: tewarir@us.ibm.com
Charles Lever (editor)
Oracle Corporation
1015 Granger Avenue
Ann Arbor, MI 48104
United States
Phone: +1 248-614-5091
EMail: chuck.lever@oracle.com📦 where this page comes from
- ietf: rfc7532 2015-03
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms