RFC 7533

Administration Protocol for Federated File Systems

📅 published March 2015, from ietf

RFC 7533: Administration Protocol for Federated File Systems 🎀

Okay bestie, this is RFC 7533 💅 It's an Internet Standards Track document, so it's official, not just a suggestion. It came out in March 2015 and was written by J. Lentini (NetApp), R. Tewari (IBM Almaden), and C. Lever, Ed. (Oracle Corporation). Its ISSN is 2070-1721. No obsoletes or updates are listed in its header, so it doesn't replace or change any other RFC 🦋

Abstract 💖

okay so this doc is about the administration protocol for a federated file system (FedFS). It lets file access and namespace traversal work across a bunch 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, so together they provide one namespace made of the file systems that each server physically hosts and exports ✨

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 got public review, and the Internet Engineering Steering Group (IESG) approved it for publication 👑 For more on Internet Standards, check Section 2 of RFC 5741.

For info on the current status of this doc, any errata, and how to give feedback, go to http://www.rfc-editor.org/info/rfc7533 🌈

Copyright Notice ©

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stand on the date this document was published. Please read these carefully, bestie, because they spell out your rights and restrictions for this document 🙈 Code Components pulled from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as the Simplified BSD License describes 🔥

This document may contain material from IETF Documents or IETF Contributions that was published or made publicly available before November 10, 2008. The people who control the copyright in some of that material may not have given the IETF Trust permission to allow modifications outside the IETF Standards Process. Unless you get an adequate license from those copyright holders, 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. The only exceptions are formatting it for publication as an RFC or translating it into languages other than English 🦋

Table of Contents 🧚

   1. Introduction ....................................................4
      1.1. Definitions ................................................4
      1.2. Requirements Language ......................................6
   2. Protocol ........................................................7
   3. Error Values ...................................................12
   4. Data Types .....................................................15
      4.1. FedFsNsdbName Equality ....................................17
   5. Procedures .....................................................17
      5.1. FEDFS_NULL ................................................18
           5.1.1. Synopsis ...........................................18
           5.1.2. Description ........................................18
           5.1.3. Errors .............................................18
      5.2. FEDFS_CREATE_JUNCTION .....................................18
           5.2.1. Synopsis ...........................................18
           5.2.2. Description ........................................18
           5.2.3. Errors .............................................20
      5.3. FEDFS_DELETE_JUNCTION .....................................20
           5.3.1. Synopsis ...........................................20
           5.3.2. Description ........................................20
           5.3.3. Errors .............................................22
      5.4. FEDFS_LOOKUP_JUNCTION .....................................22
           5.4.1. Synopsis ...........................................22
           5.4.2. Description ........................................22
           5.4.3. Errors .............................................25
      5.5. FEDFS_CREATE_REPLICATION ..................................26
           5.5.1. Synopsis ...........................................26
           5.5.2. Description ........................................26
           5.5.3. Errors .............................................27
      5.6. FEDFS_DELETE_REPLICATION ..................................27
           5.6.1. Synopsis ...........................................27
           5.6.2. Description ........................................27
           5.6.3. Errors .............................................28
      5.7. FEDFS_LOOKUP_REPLICATION ..................................28
           5.7.1. Synopsis ...........................................28
           5.7.2. Description ........................................28
           5.7.3. Errors .............................................29
      5.8. FEDFS_SET_NSDB_PARAMS .....................................30
           5.8.1. Synopsis ...........................................30
           5.8.2. Description ........................................30
           5.8.3. Errors .............................................31
      5.9. FEDFS_GET_NSDB_PARAMS .....................................31
           5.9.1. Synopsis ...........................................31
           5.9.2. Description ........................................31
           5.9.3. Errors .............................................32
      5.10. FEDFS_GET_LIMITED_NSDB_PARAMS ............................32
           5.10.1. Synopsis ..........................................32
           5.10.2. Description .......................................32
           5.10.3. Errors ............................................33
   6. Security Considerations ........................................33
   7. IANA Considerations ............................................34
   8. References .....................................................34
      8.1. Normative References ......................................34
      8.2. Informative References ....................................35
   Acknowledgments ...................................................36
   Authors' Addresses ................................................37

1. Introduction ✨

A federated file system lets you access files and traverse namespaces in a uniform, secure, and consistent way across many independent fileservers inside one enterprise (and possibly across several enterprises), with reasonably good performance 🍓

Building a namespace that spans multiple fileservers has traditionally been hard, and there are two reasons why 😭 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 might come with proprietary management tools, and sometimes an admin can use those tools to build a shared namespace out of the exported file systems. But relying on vendor-proprietary tools doesn't work in bigger enterprises, or when collaborating across enterprises, because the system will likely contain fileservers running different software, each with their own protocols, and there's no common protocol to manage the namespace or exchange namespace information 💀

The requirements for federated namespaces are described in [RFC5716] 🧚

The protocol for federated file systems described in [RFC7532] lets fileservers from different vendors and/or with different administrators cooperatively build a namespace 🫶

This document describes the protocol administrators use to configure the fileservers and construct the namespace. Stay tuned, because this is just part 1 💖

1.1. Definitions 📖

okay so before we get into the good stuff, we need the vocab 💅 these are the words the whole spec is built on, so bestie, pay attention 🫶

Administrator: a user with the necessary authority to initiate administrative tasks on one or more servers. 👑
Admin Entity: a server or agent that administers a collection of fileservers and persistently stores the namespace information. 🗂️
File-Access Client: standard off-the-shelf, network-attached storage (NAS) client software that communicates with fileservers using a standard file-access protocol. 💻
Federation: a set of fileserver collections and singleton fileservers that use a common set of interfaces and protocols in order to provide to file-access clients a federated namespace accessible through a file system access protocol. 🌈
Fileserver: a server that stores physical fileset data or refers file-access clients to other fileservers. A fileserver provides access to its shared file system data via a file-access protocol. 🗃️
Fileset: the abstraction of a set of files and the directory tree that contains them. A fileset is the fundamental unit of data management in the federation. ✨

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 implement filesets. The fileset does not need to be rooted at the root of the file system, nor at the export point for the file system. 🧚

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 such as the Network File System (NFS) version 4 [RFC7530] or the Common Internet File System (CIFS) [MS-SMB] [MS-SMB2] [MS-CIFS]. 🦋
FSL (Fileset Location): the location of the implementation of a fileset at a particular moment in time. An FSL MUST be something that can be translated into a protocol-specific description of a resource that a file-access client can access directly, such as an fs_locations attribute (for NFSv4) or a share name (for CIFS). 📍
FSN (Fileset Name): a platform-independent and globally unique name for a fileset. Two FSLs that implement replicas of the same fileset MUST have the same FSN, and if a fileset is migrated from one location to another, the FSN of that fileset MUST remain the same. 🏷️
Junction: a file system object used to link a directory name in the current fileset with an object within another fileset. The server-side "link" from a leaf node in one fileset to the root of another fileset. 🔗
Namespace: a filename/directory tree that a sufficiently authorized file-access client can observe. 🌳
NSDB (Namespace Database) Service: a service that maps FSNs to FSLs. The NSDB may also be used to store other information, such as annotations for these mappings and their components. 🗺️
NSDB Node: the name or location of a server that implements part of the NSDB service and is responsible for keeping track of the FSLs (and related information) that implement a given partition of the FSNs. 🧭
Referral: a server response to a file-access client access that directs the client to evaluate the current object as a reference to an object at a different location (specified by an FSL) in another fileset and possibly hosted on another fileserver. The client re-attempts the access to the object at the new location. 📬
Replica: a redundant implementation of a fileset. Each replica shares the same FSN but has a 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. 💜

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 a unit. A server collection may be administered with vendor-specific software. 🏢

The namespace provided by a server collection could be part of the federated namespace. 🌍

Singleton Server: a server collection containing only one server; a stand-alone fileserver. 🦄

1.2. Requirements Language 🎀

okay this part is the rulebook for the capital letters 😭 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]. so when you see them in caps, that's the official meaning, no cap 💯

2. Protocol 🎀

okay so the admin operations in this spec get carried over the Open Network Computing (ONC) RPC protocol [RFC5531]. bestie, the data structures for the parameters and return values are written in External Data Representation (XDR) [RFC4506] 💅

the XDR definitions are formatted so you can pull them straight out of the doc without copy-pasting like a caveman 🙈 there's a tiny shell script for it:

#!/bin/sh
grep '^ *///' | sed 's?^ */// ??' | sed 's?^ *///$??'

so if you save that as "extract.sh" and the document is "spec.txt", you just run:

sh extract.sh < spec.txt > admin1.xdr

the script strips leading white space from each line, plus that "///" sentinel, and you end up with clean XDR 🧚

the protocol definition comes next. first we set up the basic constants and structures, then we get to the procedures, so it reads like a proper story 📖✨

/*
 * 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.
 */

enum FedFsStatus {
 FEDFS_OK                                 = 0,
 FEDFS_ERR_ACCESS                         = 1,
 FEDFS_ERR_BADCHAR                        = 2,
 FEDFS_ERR_BADNAME                        = 3,
 FEDFS_ERR_NAMETOOLONG                    = 4,
 FEDFS_ERR_LOOP                           = 5,
 FEDFS_ERR_BADXDR                         = 6,
 FEDFS_ERR_EXIST                          = 7,
 FEDFS_ERR_INVAL                          = 8,
 FEDFS_ERR_IO                             = 9,
 FEDFS_ERR_NOSPC                          = 10,
 FEDFS_ERR_NOTJUNCT                       = 11,
 FEDFS_ERR_NOTLOCAL                       = 12,
 FEDFS_ERR_PERM                           = 13,
 FEDFS_ERR_ROFS                           = 14,
 FEDFS_ERR_SVRFAULT                       = 15,
 FEDFS_ERR_NOTSUPP                        = 16,
 FEDFS_ERR_NSDB_ROUTE                     = 17,
 FEDFS_ERR_NSDB_DOWN                      = 18,
 FEDFS_ERR_NSDB_CONN                      = 19,
 FEDFS_ERR_NSDB_AUTH                      = 20,
 FEDFS_ERR_NSDB_LDAP                      = 21,
 FEDFS_ERR_NSDB_LDAP_VAL                  = 22,
 FEDFS_ERR_NSDB_NONCE                     = 23,
 FEDFS_ERR_NSDB_NOFSN                     = 24,
 FEDFS_ERR_NSDB_NOFSL                     = 25,
 FEDFS_ERR_NSDB_RESPONSE                  = 26,
 FEDFS_ERR_NSDB_FAULT                     = 27,
 FEDFS_ERR_NSDB_PARAMS                    = 28,
 FEDFS_ERR_NSDB_LDAP_REFERRAL             = 29,
 FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL         = 30,
 FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED = 31,
 FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL      = 32,
 FEDFS_ERR_PATH_TYPE_UNSUPP               = 33,
 FEDFS_ERR_DELAY                          = 34,
 FEDFS_ERR_NO_CACHE                       = 35,
 FEDFS_ERR_UNKNOWN_CACHE                  = 36,
 FEDFS_ERR_NO_CACHE_UPDATE                = 37
};

typedef opaque                 utf8string<>;
typedef utf8string             ascii_REQUIRED4;
typedef utf8string             utf8val_REQUIRED4;

typedef opaque FedFsUuid[16];

struct FedFsNsdbName {
        unsigned int           port;
        utf8val_REQUIRED4      hostname;
};

typedef ascii_REQUIRED4 FedFsPathComponent;
typedef FedFsPathComponent FedFsPathName<>;

struct FedFsFsn {
        FedFsUuid              fsnUuid;
        FedFsNsdbName          nsdbName;
};

enum FedFsFslType {
 FEDFS_NFS_FSL = 0
};

struct FedFsNfsFsl {
        FedFsUuid              fslUuid;
        unsigned int           port;
        utf8val_REQUIRED4      hostname;
        FedFsPathName          path;
};

union FedFsFsl switch(FedFsFslType type) {
 case FEDFS_NFS_FSL:
        FedFsNfsFsl            nfsFsl;
};

enum FedFsPathType {
 FEDFS_PATH_SYS = 0,
 FEDFS_PATH_NFS = 1
};

union FedFsPath switch(FedFsPathType type) {
 case FEDFS_PATH_SYS: /* administrative path */
        FedFsPathName          adminPath;
 case FEDFS_PATH_NFS: /* NFS namespace path */
        FedFsPathName          nfsPath;
};

struct FedFsCreateArgs {
        FedFsPath              path;
        FedFsFsn               fsn;
};

enum FedFsResolveType {
 FEDFS_RESOLVE_NONE  = 0,
 FEDFS_RESOLVE_CACHE = 1,
 FEDFS_RESOLVE_NSDB  = 2
};

struct FedFsLookupArgs {
        FedFsPath              path;
        FedFsResolveType       resolve;
};

struct FedFsLookupResOk {
        FedFsFsn               fsn;
        FedFsFsl               fsl<>;
};

struct FedFsLookupResReferralVal {
        FedFsNsdbName          targetNsdb;
        unsigned int           ldapResultCode;
};

union FedFsLookupRes switch (FedFsStatus status) {
 case FEDFS_OK:
 case FEDFS_ERR_NO_CACHE_UPDATE:
        FedFsLookupResOk           resok;
 case FEDFS_ERR_NSDB_LDAP_VAL:
        unsigned int               ldapResultCode;
 case FEDFS_ERR_NSDB_LDAP_REFERRAL:
 case FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL:
        FedFsNsdbName              targetNsdb;
 case FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL:
        FedFsLookupResReferralVal  resReferralVal;
 default:
        void;
};

enum FedFsConnectionSec {
 FEDFS_SEC_NONE = 0,
 FEDFS_SEC_TLS = 1 /* StartTLS mechanism; RFC 4513, Section 3 */
};

union FedFsNsdbParams switch (FedFsConnectionSec secType) {
 case FEDFS_SEC_TLS:
        opaque                   secData<>;
 default:
        void;
};

struct FedFsSetNsdbParamsArgs {
        FedFsNsdbName            nsdbName;
        FedFsNsdbParams          params;
};

union FedFsGetNsdbParamsRes switch (FedFsStatus status) {
 case FEDFS_OK:
        FedFsNsdbParams          params;
 default:
        void;
};

union FedFsGetLimitedNsdbParamsRes switch (FedFsStatus status) {
 case FEDFS_OK:
        FedFsConnectionSec       secType;
 default:
        void;
};

program FEDFS_PROG {
 version FEDFS_V1 {
     void FEDFS_NULL(void) = 0;
     FedFsStatus FEDFS_CREATE_JUNCTION(
                  FedFsCreateArgs) = 1;
     FedFsStatus FEDFS_DELETE_JUNCTION(
                  FedFsPath) = 2;
     FedFsLookupRes FEDFS_LOOKUP_JUNCTION(
                  FedFsLookupArgs) = 3;
     FedFsStatus FEDFS_CREATE_REPLICATION(
                  FedFsCreateArgs) = 7;
     FedFsStatus FEDFS_DELETE_REPLICATION(
                  FedFsPath) = 8;
     FedFsLookupRes FEDFS_LOOKUP_REPLICATION(
                  FedFsLookupArgs) = 9;
     FedFsStatus FEDFS_SET_NSDB_PARAMS(
                  FedFsSetNsdbParamsArgs) = 4;
     FedFsGetNsdbParamsRes FEDFS_GET_NSDB_PARAMS(
                  FedFsNsdbName) = 5;
     FedFsGetLimitedNsdbParamsRes FEDFS_GET_LIMITED_NSDB_PARAMS(
                  FedFsNsdbName) = 6;
 } = 1;
} = 100418;

3. Error Values ✨

okay so, successful operations just come back with a status of FEDFS_OK 💖 Anything that fails starts with a status that is not FEDFS_OK, and that status tells you why it went wrong 😭

A lot of these error names and their meanings (and the wording of their descriptions) were borrowed from the NFSv4 spec [RFC7530]. ngl, the numeric values are totally different though 🙈 For example, FEDFS_ERR_ACCESS was inspired by NFSv4's NFS4ERR_ACCESS, but the numbers don't match 🔢

Also, the status of a failed operation will usually only tell you the first error the server ran into while trying to run it. Just one, bestie 💅

FEDFS_OK: No errors were encountered. The operation was a success. 🎉
FEDFS_ERR_ACCESS: Permission denied. The caller doesn't have the right permission to do the operation they asked for. 🚫
FEDFS_ERR_BADCHAR: A UTF-8 string has a character that the server doesn't support in the context where it's being used. 🫠
FEDFS_ERR_BADNAME: A name string in a request is made of valid UTF-8 characters the server supports, but that name isn't allowed as a valid name for the current operation. 🙅‍♀️
FEDFS_ERR_NAMETOOLONG: Returned when the pathname in an operation goes over the server's implementation limit. 📏
FEDFS_ERR_LOOP: Returned when too many symbolic links were hit while resolving a pathname. 🔁
FEDFS_ERR_BADXDR: The server hit an XDR decoding error while processing an operation. 💀
FEDFS_ERR_EXIST: The junction you specified already exists. 🚧
FEDFS_ERR_INVAL: Invalid argument for an operation. ❌
FEDFS_ERR_IO: A hard error happened while processing the requested operation. 💥
FEDFS_ERR_NOSPC: The requested operation would've made the server's file system go over some limit (for example, if there's a fixed number of junctions per fileset or per server). 📦
FEDFS_ERR_NOTJUNCT: The caller gave a path that doesn't end in a junction, for an operation that needs the last part of the path to be a junction. 🛤️
FEDFS_ERR_NOTLOCAL: The caller gave a path with a junction in any spot other than the last component. 🙃
FEDFS_ERR_PERM: The operation wasn't allowed because the caller is either not a privileged user or not the owner of an object the operation would change. 👑
FEDFS_ERR_ROFS: Someone tried a modifying operation on a read-only file system. 🔒
FEDFS_ERR_SVRFAULT: An unexpected non-protocol error happened on the server. 🫣
FEDFS_ERR_NSDB_ROUTE: The fileserver couldn't find a route to the NSDB. 🗺️
FEDFS_ERR_NSDB_DOWN: The fileserver figured out the NSDB is down. 📉
FEDFS_ERR_NSDB_CONN: The fileserver couldn't set up a connection with the NSDB. 🔌
FEDFS_ERR_NSDB_AUTH: The fileserver couldn't authenticate and set up a secure connection with the NSDB. 🔐
FEDFS_ERR_NSDB_LDAP: A Lightweight Directory Access Protocol (LDAP) error happened on the connection between the fileserver and the NSDB. 🌀
FEDFS_ERR_NSDB_LDAP_VAL: Same error as FEDFS_ERR_NSDB_LDAP, but it lets the LDAP protocol error value get sent back to an ADMIN protocol client. 🔁
FEDFS_ERR_NSDB_NONCE: The fileserver couldn't find the NSDB Container Entry (NCE) in the right NSDB. 🔍
FEDFS_ERR_NSDB_NOFSN: The fileserver couldn't find the given FSN in the right NSDB. 🕵️‍♀️
FEDFS_ERR_NSDB_NOFSL: The fileserver couldn't find any FSLs for the given FSN in the right NSDB. 🫥
FEDFS_ERR_NSDB_RESPONSE: The fileserver got a malformed response from the NSDB. This includes times when an NSDB entry (like an FSN or FSL) is missing a required attribute. 🧩
FEDFS_ERR_NSDB_FAULT: An unexpected error related to the NSDB happened. 😵
FEDFS_ERR_NSDB_PARAMS: The fileserver doesn't have any connection parameters on record for the specified NSDB. 📭
FEDFS_ERR_NSDB_LDAP_REFERRAL: The fileserver got an LDAP referral it couldn't follow. ↩️
FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL: Same error as FEDFS_ERR_NSDB_LDAP_REFERRAL, but it lets the LDAP protocol error value get sent back to an ADMIN protocol client. 🔄
FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED: The fileserver got an LDAP referral and chose not to follow it, either because it doesn't support following LDAP referrals or because LDAP referral following is turned off. 🙅
FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL: The fileserver got an LDAP referral and chose not to follow it, since it had no NSDB parameters for the NSDB that the referral was pointing at. 🤷‍♀️
FEDFS_ERR_PATH_TYPE_UNSUPP: The fileserver doesn't support the specified FedFsPathType value. 🚫
FEDFS_ERR_NOTSUPP: The fileserver doesn't support the specified procedure. 🛑
FEDFS_ERR_DELAY: The fileserver started the request but couldn't finish it in a timely way. The ADMIN protocol client should wait a bit and then retry the request with a new RPC transaction ID. ⏳
FEDFS_ERR_NO_CACHE: The fileserver doesn't have an FSN-to-FSL cache. 🗄️
FEDFS_ERR_UNKNOWN_CACHE: The software getting the ONC RPC request doesn't know whether the fileserver has an FSN-to-FSL cache, or it can't talk to the cache if one exists. 👻
FEDFS_ERR_NO_CACHE_UPDATE: The fileserver couldn't update its FSN-to-FSL cache. 🔄❌

4. Data Types 🎀

okay the basic data types we talked about up top get formatted like this, and it's giving structure 🧁

FedFsUuid: This is a universally unique identifier (UUID) as described in [RFC4122], as a version 4 UUID. The UUID MUST be formatted in network byte order. 🔢

FedFsNsdbName: This is a (hostname, port) pair. 🧑‍💻

The hostname is a variable-length UTF-8 string that shows where an NSDB lives on the network, written in DNS name notation. It SHOULD be prepared using the domain name rules in Section 12.6 ("Types with Processing Defined by Other Internet Areas") of [RFC7530]. The DNS name MUST be written as a fully qualified domain name. 🌐

The port value in the FedFsNsdbName tells you the LDAP port on the NSDB (see [RFC4511]). The value MUST be in the range 0 to 65535. A value of 0 means the standard LDAP port number, 389, MUST be assumed. 🔌

FSNs are immutable and invariant. The attributes of an FSN, including the fedfsNsdbName, are expected to stay constant. So a FedFsNsdbName MUST NOT contain a network address, like an IPv4 or IPv6 address, because that would basically lock the network address in forever 🙅‍♀️🔒

FedFsPathComponent: This is a case-sensitive UTF-8 string with a file system path component in it. The component names of an NFSv4 pathname MUST be prepared using the component name rules in Section 12 ("Internationalization") of [RFC7530] before the path component of an NFS URI gets encoded. 🛤️

FedFsPathName: This is a variable-length array of FedFsPathComponent values that represents a file system path. The path's first component goes in the first position of the array, the second component goes in the second position, and so on. 📚

The path "/" MUST be encoded as an array with zero components. 🫧

A FedFsPathName MUST NOT contain any zero-length components. 🚫

FedFsPath: This is a pathname container. The format and semantics of the pathname are defined by the FedFsPathType value. 📦

FedFsPathType: This is the type-specific description of a pathname. 🏷️

A FEDFS_PATH_SYS is an implementation-dependent administrative pathname. For example, it could be a local file system path. 🖥️

A FEDFS_PATH_NFS is a pathname in the NFSv4 server's single-server namespace. 🗂️

FedFsNsdbParams: This is a set of parameters for connecting to an NSDB. Conceptually, the fileserver has a data structure that maps an NSDB name (DNS name and port value) to these LDAP connection parameters. It's giving map energy 🗺️

The secType field tells you which security mechanism MUST be used to protect all connections to the NSDB with those connection parameters. 🔐

A value of FEDFS_SEC_NONE means a transport security mechanism MUST NOT be used when connecting to the NSDB. In this case, the secData array has a length of zero. 🫥

A value of FEDFS_SEC_TLS means the StartTLS security mechanism [RFC4513] MUST be used to protect all connections to the NSDB. In this case, the secData array holds an X.509v3 root certificate in binary DER format [RFC5280], which covers the Transport Layer Security (TLS) requirement that root keys be distributed separately from the TLS protocol. 🎟️ The certificate MUST be used by the fileserver as a trust anchor to validate the NSDB's TLS server certificate list chain (see Section 7.4.2 of [RFC5246]), and that's how the identity of the NSDB gets authenticated. 🪪 The certificate could be a certificate authority's or a self-signed certificate.

⚠️ To make sure this security configuration info doesn't cause vulnerabilities for other services, trust anchors provided through secData MUST only be used for the NSDB service. They should NOT be installed as system-wide trust anchors for other services.

Most popular TLS libraries have ways to do this, like pointing at a private file system location for the certificates. 📁✨

4.1. FedFsNsdbName Equality 💅

Two FedFsNsdbNames are considered equal if their hostname and port fields contain the same values. The only exception is that a value of 0 in the port field always matches the standard LDAP port number, 389. 🫶

So, for example, (nsdb.example.com, 0) is considered equal to (nsdb.example.com, 389), but it's NOT equal to (nsdb.example.com, 1066) because the port numbers are different, or to (nsdb.foo.example.com, 389) because the hostnames are different. 🙌

5. Procedures 💅

okay so, the procedures from Section 2 get the full breakdown in the next bits 🧚 fileservers that act as "internal" nodes in the federated namespace MUST implement these:

FEDFS_NULL
FEDFS_CREATE_JUNCTION
FEDFS_DELETE_JUNCTION
FEDFS_LOOKUP_JUNCTION
FEDFS_SET_NSDB_PARAMS
FEDFS_GET_NSDB_PARAMS
FEDFS_GET_LIMITED_NSDB_PARAMS

and then they SHOULD also do these three replication ones 🫶

FEDFS_CREATE_REPLICATION
FEDFS_DELETE_REPLICATION
FEDFS_LOOKUP_REPLICATION

leaf nodes are the fileservers that host the filesets junctions point to but don't have any junctions of their own 🌸 they're not required to implement any of these operations, which is honestly so relatable (they just chill and host the good stuff 🙈)

now the replica part is giving main character energy 👑 any operation that changes a replicated fileset MUST update every single replica in a consistent way. ideally, all the replicas SHOULD be updated before the operation returns. if some replicas are offline, the operation MAY still succeed, BUT the changes MUST be applied before those replicas come back online 😭 we're assuming the replicas get updated through some protocol that keeps state consistent across the set, so they all converge to the same state within a bounded number of successful message exchanges between the servers hosting them ✨

5.1. FEDFS_NULL 🎀

5.1.1. Synopsis

this is just the standard NULL procedure 💖

5.1.2. Description

the null RPC is included by convention in every ONC RPC protocol, so it's a classic. it takes no arguments and gives back no result 🍓

5.1.3. Errors

None.

5.2. FEDFS_CREATE_JUNCTION 🦋

5.2.1. Synopsis

create a new junction from a location on the server (a pathname) to an FSN ✨

5.2.2. Description

this operation makes a junction going from a server-relative path to a (possibly remote) fileset named by the given FSN 💅

the junction directory is identified by a pathname, which is an array of one or more UTF-8 path component strings. it isn't required that this path be reachable in any other way (like by a file-access client) 🌈 also, this path doesn't show up in the federated namespace unless it's a total coincidence. there's no requirement that the global namespace mirror the server namespace, and the path doesn't have to be relative to the server pseudo-root either. it doesn't need to be NFS-accessible, though the junction will be pretty useless if the directory isn't reachable over NFS 😭

if the fileset is read-only, this operation MUST report that with a status of FEDFS_ERR_ROFS 🙅‍♀️

if the path has a character the server doesn't support, the status FEDFS_ERR_BADCHAR MUST be returned 💀

the path is REQUIRED to exist and be completely local to the server. it MUST NOT contain a junction. if the last component is already a junction (so you're trying to make a junction where one already lives), this operation MUST return FEDFS_ERR_EXIST, even if the new junction is identical to the current one 🙈 if any other component of the path is a junction, the operation MUST fail with FEDFS_ERR_NOTLOCAL. the path might contain a symbolic link (if the local server supports them), but walking the path MUST stay inside the server-local namespace 🧚

if any component of the path doesn't exist, the operation MUST fail with FEDFS_ERR_INVAL 🥀

the server MAY enforce local permissions on the path, including the final component. if the server wants to say a path can't be traversed because of permissions, or the final component is an unexecutable or unwritable directory, the operation MUST fail with FEDFS_ERR_ACCESS 🔐

the operation SHOULD fail with FEDFS_ERR_NSDB_PARAMS if the fileserver has no connection parameters on record for the specified NSDB. OR the server may let it go ahead using some set of default NSDB connection parameters ✨

the association between the path and the FSN MUST be durable before the operation returns successfully. if the return code says success, then the junction was created and it's immediately accessible 🎉

if it works, later references from NFSv4.0 [RFC7530] or NFSv4.1 [RFC5661] clients to the directory that got replaced by the junction will get a referral to a current location of the target fileset [RFC7532] 💜

the effective permissions of the directory being turned into a junction are the permissions of the root directory of the target fileset. the directory's original permissions (and any other attributes it had) get swallowed up by the junction 🫠

this operation doesn't create a fileset at the location the junction targets. if the target fileset doesn't exist, the junction still gets made anyway, and an NFS client will find out the fileset is missing when it walks through the junction 👀

5.2.3. Errors

FEDFS_ERR_ACCESS
FEDFS_ERR_BADCHAR
FEDFS_ERR_BADNAME
FEDFS_ERR_NAMETOOLONG
FEDFS_ERR_LOOP
FEDFS_ERR_BADXDR
FEDFS_ERR_EXIST
FEDFS_ERR_INVAL
FEDFS_ERR_IO
FEDFS_ERR_NOSPC
FEDFS_ERR_NOTLOCAL
FEDFS_ERR_PERM
FEDFS_ERR_ROFS
FEDFS_ERR_SVRFAULT
FEDFS_ERR_PATH_TYPE_UNSUPP
FEDFS_ERR_NOTSUPP
FEDFS_ERR_DELAY

5.3. FEDFS_DELETE_JUNCTION 🥂

5.3.1. Synopsis

delete an existing junction from a location on the server (a pathname) 🌷

5.3.2. Description

this operation removes a junction that's specified by a server-relative path 💅

same as with FEDFS_CREATE_JUNCTION, the junction is identified by a pathname, an array of one or more UTF-8 path component strings. it doesn't have to be reachable in any other way (like by a file-access client) 🦋 this path also doesn't appear in the federated namespace unless it's a coincidence. the global namespace doesn't have to reflect the server namespace, and the path doesn't have to be relative to the server pseudo-root. it doesn't need to be NFS-accessible either ✨

if the fileset is read-only, this operation MUST report that with FEDFS_ERR_ROFS 🙅‍♀️

if the path has a character the server doesn't support, the status FEDFS_ERR_BADCHAR MUST be returned 💀

the path you use to delete a junction might not be the same path you used to create it 😭 if the server's namespace has changed, the junction could now show up at a different path than where it was created. if there's more than one valid path to the junction, any of them works 🧚

the path is REQUIRED to exist and be completely local to the server. it MUST NOT contain a junction, EXCEPT as the final component, which MUST be a junction. if any other component is a junction, this operation MUST fail with FEDFS_ERR_NOTLOCAL. if the last component isn't a junction, the operation MUST return FEDFS_ERR_NOTJUNCT. the path might contain a symbolic link (if the local server supports it), but walking the path MUST stay inside the server-local namespace 🌸

the server MAY enforce local permissions on the path, including the final component. if the server wants to say the path can't be traversed because of permissions, or the final component is an unexecutable or unwritable directory, the operation MUST fail with FEDFS_ERR_ACCESS 🔐

the removal of the association between the path and the FSN MUST be durable before the operation returns successfully. if the return code says success, the junction was destroyed 🎀

the effective permissions and other attributes of the directory restored by this operation SHOULD be identical to what they were before the junction was created ✨

after the junction is removed, the fileserver MAY check whether any of its remaining junctions reference the NSDB from the removed junction's FSN. if nothing references that NSDB anymore, the fileserver MAY delete that NSDB's connection parameters 🧹

5.3.3. Errors

FEDFS_ERR_ACCESS
FEDFS_ERR_BADCHAR
FEDFS_ERR_BADNAME
FEDFS_ERR_NAMETOOLONG
FEDFS_ERR_LOOP
FEDFS_ERR_BADXDR
FEDFS_ERR_INVAL
FEDFS_ERR_IO
FEDFS_ERR_NOTJUNCT
FEDFS_ERR_NOTLOCAL
FEDFS_ERR_PERM
FEDFS_ERR_ROFS
FEDFS_ERR_SVRFAULT
FEDFS_ERR_PATH_TYPE_UNSUPP
FEDFS_ERR_NOTSUPP
FEDFS_ERR_DELAY

5.4. FEDFS_LOOKUP_JUNCTION 🔍

5.4.1. Synopsis

this one asks the server what the current value of the junction is (if there even is one) at a given path in the server namespace 🧚💖

5.4.2. Description 🎀

okay bestie, so this operation asks a server "hey, does this path end in a junction?" 🦋 If it does, you get back the FSN the junction refers to, plus whether the fileserver can actually resolve it ✨

ordinary NFSv4 operations have no general way to tell if something is a junction, ngl 💀 the NFSv4 protocol doesn't specify any encoding that can represent that info, so this op is the one that does it 🫶

same as FEDFS_CREATE_JUNCTION, the pathname MUST be in the form of an array of one or more UTF-8 path component strings. 💅 it is not required that this path be accessible in any other manner (e.g., to a file-access client). this path doesn't show up in the federated namespace, except by coincidence 🙈 there is no requirement that the global namespace reflect the server namespace, and the path isn't required to be relative to the server pseudo-root either. it doesn't need to be a path that is accessible via NFS.

if the path contains a character that isn't supported by the server, then status FEDFS_ERR_BADCHAR MUST be returned. no exceptions, periodt 💅

the path you use to look up a junction might not be the same path you used to create it 🦋 if the namespace on the server has changed, a junction might now show up at a different path than where it was created. if there's more than one valid path to the junction, any of them might be used ✨

the path is REQUIRED to exist and be completely local to the server. it MUST NOT contain a junction, except as the final component 🌸 if any other component of the path is a junction, then this operation MUST fail with status FEDFS_ERR_NOTLOCAL. if the last component of the path is not a junction, then this operation MUST return the status FEDFS_ERR_NOTJUNCT. the path might contain a symbolic link (if supported by the local server), but the traversal of the path MUST remain within the server-local namespace 🧚

the server MAY enforce the local permissions on the path, including the final component. if a server wants to report that a path can't be traversed because of insufficient permissions, or the final component is an unexecutable or unwritable directory, then the operation MUST fail with status FEDFS_ERR_ACCESS 🔥

if the junction exists, the resolve parameter lets you test the fileserver's ability to resolve the junction 👑 if the junction does not exist, the fileserver will ignore the resolve parameter.

if the junction exists and the resolve parameter is set to FEDFS_RESOLVE_NONE, the fileserver MUST NOT attempt to resolve the FSN. this lets an administrator grab the junction's FSN even if the resolution would fail 😭 therefore, on success, the result of a FEDFS_RESOLVE_NONE call returns a zero-length fsl list in the FedFsLookupResOk structure.

if the junction exists and the resolve parameter is set to FEDFS_RESOLVE_CACHE, the fileserver MUST attempt to resolve the FSN using its FSL cache, if one exists. the fileserver MUST NOT resolve the FSN by contacting the appropriate NSDB. if the fileserver's cache doesn't have a mapping for the FSN in question, the result of the operation MUST be FEDFS_OK with 0 elements in the FedFsLookupResOk structure's fsl array. the operation MAY fail with status FEDFS_ERR_NO_CACHE if the fileserver doesn't contain an FSN-to-FSL cache, or with status FEDFS_ERR_UNKNOWN_CACHE if the state of the cache is unknown 🌈

if the junction exists and the resolve parameter is set to FEDFS_RESOLVE_NSDB, the fileserver MUST attempt to resolve the FSN by contacting the appropriate NSDB. the FSN MUST NOT be resolved using cached information. the resolution MAY fail with FEDFS_ERR_NSDB_ROUTE, FEDFS_ERR_NSDB_DOWN, FEDFS_ERR_NSDB_CONN, FEDFS_ERR_NSDB_AUTH, FEDFS_ERR_NSDB_LDAP, FEDFS_ERR_NSDB_LDAP_VAL, FEDFS_ERR_NSDB_NOFSN, FEDFS_ERR_NSDB_NOFSL, FEDFS_ERR_NSDB_NONCE, FEDFS_ERR_NSDB_RESPONSE, FEDFS_ERR_NSDB_FAULT, FEDFS_ERR_NSDB_LDAP_REFERRAL, FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL, FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED, or FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL, depending on the nature of the failure 💀

in the case of an LDAP failure, the fileserver MUST return either FEDFS_ERR_NSDB_LDAP or FEDFS_ERR_NSDB_LDAP_VAL. FEDFS_ERR_NSDB_LDAP means an LDAP protocol error happened during the resolution. FEDFS_ERR_NSDB_LDAP_VAL also means an LDAP protocol error happened during the resolution, and it lets the LDAP protocol error value come back in the FedFsLookupRes's ldapResultCode field (see the resultCode values in Section 4.1.9 of [RFC4511]) 🍓

if the NSDB responds with an LDAP referral, either the Referral type defined in Section 4.1.10 of [RFC4511] or the SearchResultReference type defined in Section 4.5.3 of [RFC4511], the fileserver SHOULD process the LDAP referral using the same policies as the fileserver's file-access protocol server. the fileserver MUST indicate a failure while processing the LDAP referral using FEDFS_ERR_NSDB_LDAP_REFERRAL, FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL, FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED, or FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL. the FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL is analogous to the FEDFS_ERR_NSDB_LDAP_VAL error, and it lets the LDAP protocol error value come back in the FedFsLookupResReferralVal's ldapResultCode field. the FEDFS_ERR_NSDB_LDAP_REFERRAL and FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL errors let the NSDB targeted by the LDAP referral come back in the FedFsLookupRes's targetNsdb field. similarly, the FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL error includes this info in the FedFsLookupResReferralVal's targetNsdb 🦋

if the fileserver has a cache of FSL records, resolving an FSN using an NSDB SHOULD result in the cache being updated. a failure to update the cache MAY be indicated with the FEDFS_ERR_NO_CACHE_UPDATE status value, or the operation may complete successfully ✨

when updating the cache, new FSLs for the given FSN SHOULD be added to the cache, and deleted FSLs SHOULD be removed from the cache. this is so desirable because it lets an administrator proactively ask the fileserver to refresh its FSL cache 💖 for example, an administrator might want to refresh the cache when changes are made to an FSN's FSLs.

if the junction is resolved, the fileserver will include a list of UUIDs for the FSN's FSLs in the FedFsLookupResOk structure's fsl array 👑

5.4.3. Errors 🫶

FEDFS_ERR_ACCESS
FEDFS_ERR_BADCHAR
FEDFS_ERR_BADNAME
FEDFS_ERR_NAMETOOLONG
FEDFS_ERR_LOOP
FEDFS_ERR_BADXDR
FEDFS_ERR_INVAL
FEDFS_ERR_IO
FEDFS_ERR_NOTJUNCT
FEDFS_ERR_NOTLOCAL
FEDFS_ERR_PERM
FEDFS_ERR_SVRFAULT
FEDFS_ERR_NSDB_ROUTE
FEDFS_ERR_NSDB_DOWN
FEDFS_ERR_NSDB_CONN
FEDFS_ERR_NSDB_AUTH
FEDFS_ERR_NSDB_LDAP
FEDFS_ERR_NSDB_LDAP_VAL
FEDFS_ERR_NSDB_NONCE
FEDFS_ERR_NSDB_NOFSN
FEDFS_ERR_NSDB_NOFSL
FEDFS_ERR_NSDB_RESPONSE
FEDFS_ERR_NSDB_FAULT
FEDFS_ERR_NSDB_PARAMS
FEDFS_ERR_NSDB_LDAP_REFERRAL
FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL
FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED
FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL
FEDFS_ERR_PATH_TYPE_UNSUPP
FEDFS_ERR_NOTSUPP
FEDFS_ERR_DELAY
FEDFS_ERR_NO_CACHE
FEDFS_ERR_UNKNOWN_CACHE
FEDFS_ERR_NO_CACHE_UPDATE

5.5. FEDFS_CREATE_REPLICATION 🌸

5.5.1. Synopsis 🦋

set an FSN representing the replication information for the fileset containing the pathname ✨

5.5.2. Description 💅

this operation indicates the replication info to be returned for a particular fileset 🌈 an NFSv4 client might request fs_locations or fs_locations_info at any time to detect other copies of this fileset, and this operation supports that by supplying the FSN the fileserver should use to respond. this FSN should be associated with the entire fileset the path resides in, and should be used to satisfy fs_locations or fs_locations_info attribute requests whenever no junction is being accessed 🧚 if a junction is being accessed, the FSN specified by FEDFS_CREATE_JUNCTION takes precedence. setting the replication FSN on a fileset that already has a replication FSN set is allowed 💖

this operation differs from FEDFS_CREATE_JUNCTION in that it controls a fileset-wide attribute that isn't associated with a junction 👑

the server SHOULD permit this operation even on read-only filesets, but MUST return FEDFS_ERR_ROFS if this is not possible 🔥

if the path contains a character that isn't supported by the server, then status FEDFS_ERR_BADCHAR MUST be returned.

the path is REQUIRED to exist and be completely local to the server. it MUST NOT contain a junction. if any component of the path is a junction, then this operation MUST fail with status FEDFS_ERR_NOTLOCAL. the path might contain a symbolic link (if supported by the local server), but the traversal of the path MUST remain within the server-local namespace 🫶

the operation SHOULD fail with status FEDFS_ERR_NSDB_PARAMS if the fileserver doesn't have any connection parameters on record for the specified NSDB, or the server may let the operation proceed using some set of default NSDB connection parameters 🙈

the same FSN value SHOULD be associated with all replicas of a file system. depending on the underlying representation, the FSN associated with a file system might or might not be replicated automatically with the file system replication mechanism. therefore, if FEDFS_CREATE_REPLICATION is used on one replica of a file system, it SHOULD be used on all replicas 🍓

5.5.3. Errors 🎀

FEDFS_ERR_ACCESS
FEDFS_ERR_BADCHAR
FEDFS_ERR_BADNAME
FEDFS_ERR_NAMETOOLONG
FEDFS_ERR_LOOP
FEDFS_ERR_BADXDR
FEDFS_ERR_EXIST
FEDFS_ERR_INVAL
FEDFS_ERR_IO
FEDFS_ERR_NOSPC
FEDFS_ERR_NOTLOCAL
FEDFS_ERR_PERM
FEDFS_ERR_ROFS
FEDFS_ERR_SVRFAULT
FEDFS_ERR_PATH_TYPE_UNSUPP
FEDFS_ERR_NOTSUPP
FEDFS_ERR_DELAY

5.6. FEDFS_DELETE_REPLICATION 🧚

5.6.1. Synopsis 💜

remove the replication information for the fileset containing the pathname 🌈

5.6.2. Description ✨

okay so this operation removes replication info from the fileset the path lives in 🧹. Once it's gone, NFSv4 clients asking for fs_locations or fs_locations_info when there's no junction in play won't get satisfied 💅.

This one is different from FEDFS_DELETE_JUNCTION because it controls a fileset-wide attribute that isn't tied to any junction 🦋.

The server SHOULD permit this even on read-only filesets 🌸, but it MUST return FEDFS_ERR_ROFS if that's not possible 🙈.

If the path has a character the server doesn't support, then FEDFS_ERR_BADCHAR MUST be returned 💀.

The path is REQUIRED to exist and be completely local to the server 🏠. It MUST NOT contain a junction. If any component of the path is a junction, this operation MUST fail with FEDFS_ERR_NOTLOCAL 😭.

The server MAY enforce local permissions on the path, including the final component 🔐. If a server wants to say a path can't be traversed because of insufficient permissions, or because the final component is an unexecutable or unwritable directory, then the operation MUST fail with FEDFS_ERR_ACCESS 🫶.

5.6.3. Errors 🚨

   FEDFS_ERR_ACCESS
   FEDFS_ERR_BADCHAR
   FEDFS_ERR_BADNAME
   FEDFS_ERR_NAMETOOLONG
   FEDFS_ERR_LOOP
   FEDFS_ERR_BADXDR
   FEDFS_ERR_INVAL
   FEDFS_ERR_IO
   FEDFS_ERR_NOTJUNCT
   FEDFS_ERR_NOTLOCAL
   FEDFS_ERR_PERM
   FEDFS_ERR_ROFS
   FEDFS_ERR_SVRFAULT
   FEDFS_ERR_PATH_TYPE_UNSUPP
   FEDFS_ERR_NOTSUPP
   FEDFS_ERR_DELAY

5.7. FEDFS_LOOKUP_REPLICATION 🔍

5.7.1. Synopsis

Query the server to find out what replication information (if any) is currently set at the given path 👀.

5.7.2. Description

This operation asks a server whether a fileset containing the given path has replication information attached 🧐. If it does, the FSN for that replication information comes back to you 💖.

This one differs from FEDFS_LOOKUP_JUNCTION because it's asking about a fileset-wide attribute that isn't associated with a junction 🦋.

If the path contains a character that is not supported by the server, then FEDFS_ERR_BADCHAR MUST be returned 💀.

Interpretation of the resolve parameter and the procedure's results works exactly the same way as Section 5.4 does for the FEDFS_LOOKUP_JUNCTION operation 🧠✨.

5.7.3. Errors 🚨

   FEDFS_ERR_ACCESS
   FEDFS_ERR_BADCHAR
   FEDFS_ERR_BADNAME
   FEDFS_ERR_NAMETOOLONG
   FEDFS_ERR_LOOP
   FEDFS_ERR_BADXDR
   FEDFS_ERR_INVAL
   FEDFS_ERR_IO
   FEDFS_ERR_NOTJUNCT
   FEDFS_ERR_NOTLOCAL
   FEDFS_ERR_PERM
   FEDFS_ERR_SVRFAULT
   FEDFS_ERR_NSDB_ROUTE
   FEDFS_ERR_NSDB_DOWN
   FEDFS_ERR_NSDB_CONN
   FEDFS_ERR_NSDB_AUTH
   FEDFS_ERR_NSDB_LDAP
   FEDFS_ERR_NSDB_LDAP_VAL
   FEDFS_ERR_NSDB_NONCE
   FEDFS_ERR_NSDB_NOFSN
   FEDFS_ERR_NSDB_NOFSL
   FEDFS_ERR_NSDB_RESPONSE
   FEDFS_ERR_NSDB_FAULT
   FEDFS_ERR_NSDB_PARAMS
   FEDFS_ERR_NSDB_LDAP_REFERRAL
   FEDFS_ERR_NSDB_LDAP_REFERRAL_VAL
   FEDFS_ERR_NSDB_LDAP_REFERRAL_NOTFOLLOWED
   FEDFS_ERR_NSDB_PARAMS_LDAP_REFERRAL
   FEDFS_ERR_PATH_TYPE_UNSUPP
   FEDFS_ERR_NOTSUPP
   FEDFS_ERR_DELAY
   FEDFS_ERR_NO_CACHE
   FEDFS_ERR_UNKNOWN_CACHE

5.8. FEDFS_SET_NSDB_PARAMS ⚙️

5.8.1. Synopsis

Set the connection parameters for the specified NSDB 🔧.

5.8.2. Description

This operation lets an administrator set the connection parameters for a given NSDB 👑.

If there's no record for the given NSDB yet, a brand new record gets created with the specified connection parameters 🌱.

If there is already a record for the given NSDB, the existing connection parameters get replaced with the specified ones 🔁.

An NSDB is identified using a FedFsNsdbName. The rules in Section 4.1 decide when two FedFsNsdbNames count as equal 🤝.

The given NSDB doesn't need to be referenced by any junctions on the fileserver 🙌. This happens when connection parameters for a brand new NSDB get installed.

The format of the connection parameters is described in Section 4 📖.

On success, this operation returns FEDFS_OK. When it returns, the new connection parameters SHOULD be used for all subsequent LDAP connections to the given NSDB 💫. Existing connections MAY be terminated and re-established using the new connection parameters. The connection parameters SHOULD be durable across fileserver reboots 💾.

On failure, an error value telling you what kind of error happened gets returned 🙈. If the operation's associated user doesn't have sufficient permissions to create or modify NSDB connection parameters, the operation MUST return FEDFS_ERR_ACCESS 🔒.

5.8.3. Errors 🚨

   FEDFS_ERR_ACCESS
   FEDFS_ERR_BADCHAR
   FEDFS_ERR_BADNAME
   FEDFS_ERR_BADXDR
   FEDFS_ERR_INVAL
   FEDFS_ERR_IO
   FEDFS_ERR_NOSPC
   FEDFS_ERR_SVRFAULT
   FEDFS_ERR_NOTSUPP
   FEDFS_ERR_DELAY

5.9. FEDFS_GET_NSDB_PARAMS 👀

5.9.1. Synopsis

Get the connection parameters for the specified NSDB 📬.

5.9.2. Description

This operation lets an administrator fetch the connection parameters for the given NSDB, if they exist 🔍.

An NSDB is identified using a FedFsNsdbName. The rules in Section 4.1 decide when two FedFsNsdbNames count as equal 🤝.

A set of connection parameters counts as a match if its associated NSDB is equal (as defined in Section 4.1) to the operation's NSDB argument. So there's at most one set of connection parameters that can match the query this operation describes 🎯.

The format of the connection parameters is described in Section 4 📖.

On success, this operation returns FEDFS_OK and the connection parameters on record for the given NSDB 🎉.

On failure, an error value telling you what kind of error happened gets returned 🙈. This operation MUST return FEDFS_ERR_NSDB_PARAMS to say there are no connection parameters on record for the given NSDB. If the operation's associated user doesn't have sufficient permissions to view NSDB connection parameters, the operation MUST return FEDFS_ERR_ACCESS 🔒.

5.9.3. Errors 🚨

   FEDFS_ERR_ACCESS
   FEDFS_ERR_BADCHAR
   FEDFS_ERR_BADNAME
   FEDFS_ERR_BADXDR
   FEDFS_ERR_INVAL
   FEDFS_ERR_IO
   FEDFS_ERR_SVRFAULT
   FEDFS_ERR_NSDB_PARAMS
   FEDFS_ERR_NOTSUPP
   FEDFS_ERR_DELAY

5.10. FEDFS_GET_LIMITED_NSDB_PARAMS 🫣

5.10.1. Synopsis

Get a limited subset of the connection parameters for the specified NSDB 🧩.

5.10.2. Description

This operation lets an administrator peek at a limited subset of the connection parameters for the given NSDB, if they exist 👀.

An NSDB is identified using a FedFsNsdbName. The rules in Section 4.1 decide when two FedFsNsdbNames count as equal 🤝.

This operation returns a limited subset of the connection parameters. Only the FedFsConnectionSec mechanism used to protect communication between the fileserver and the NSDB is returned 🔐.

Viewing the limited subset of NSDB connection parameters returned by FEDFS_GET_LIMITED_NSDB_PARAMS MAY be a less privileged operation than viewing the entire set returned by FEDFS_GET_NSDB_PARAMS 🌷. For example, the full contents of an NSDB's connection parameters could contain sensitive information for some security mechanisms. FEDFS_GET_LIMITED_NSDB_PARAMS lets the fileserver share just a subset of the connection parameters (the security mechanism) with users who have sufficient permissions, without revealing more sensitive stuff 🫶.

On success, this operation returns FEDFS_OK and the FedFsConnectionSec value on record for the given NSDB 🎉.

On failure, an error value telling you what kind of error happened gets returned 🙈. This operation MUST return FEDFS_ERR_NSDB_PARAMS to say there are no connection parameters on record for the given NSDB. If the operation's associated user doesn't have sufficient permissions to view the subset of NSDB connection parameters this procedure returns, the operation MUST return FEDFS_ERR_ACCESS 🔒.

5.10.3. Errors 🚨

   FEDFS_ERR_ACCESS
   FEDFS_ERR_BADCHAR
   FEDFS_ERR_BADNAME
   FEDFS_ERR_BADXDR
   FEDFS_ERR_INVAL
   FEDFS_ERR_IO
   FEDFS_ERR_SVRFAULT
   FEDFS_ERR_NSDB_PARAMS
   FEDFS_ERR_NOTSUPP
   FEDFS_ERR_DELAY

6. Security Considerations 🚨🔐

bestie, this section is SERIOUS. the security stuff here protects the whole namespace and everyone's NSDB secrets, so read it like your reputation depends on it 💀

The security considerations of [RFC5531] apply to the protocol described in this document. The ONC RPC protocol supports authentication, integrity, and privacy via the RPCSEC_GSS framework [RFC2203]. Fileservers that support the FedFS administration protocol described in this document MUST support RPCSEC_GSS 🛡️.

As with NFSv4.1 (see Section 2.2.1.1.1.1 of [RFC5661]), FedFS administration protocol clients and servers MUST support RPCSEC_GSS's integrity and authentication services 🤝. FedFS administration protocol servers MUST support RPCSEC_GSS's privacy service 🔒. FedFS administration protocol clients SHOULD support RPCSEC_GSS's privacy service 💅. When RPCSEC_GSS is employed on behalf of the FedFS administration protocol, RPCSEC_GSS data integrity SHOULD be used 🧷.

It is strongly RECOMMENDED that an Access Control Service be employed to restrict access to a fileserver's FedFS administration configuration data through the FedFS administrative protocol 🚪. This is how you prevent FedFS namespace corruption and protect NSDB communication parameters 🌸.

For example, when the FedFsNsdbParams secType field value FEDFS_SEC_TLS is chosen, the payload is used to provision the trust anchor root certificate for TLS secure communication between the fileserver and the NSDB 📜. In this case, RPCSEC_GSS with data integrity SHOULD be employed along with an Access Control Service to restrict access to domain administrators 👑.

FEDFS_GET_LIMITED_NSDB_PARAMS's interaction with the NSDB's connection parameters is discussed in Section 5.10.2 🧠.

7. IANA Considerations 🎀

A range of ONC RPC program numbers was assigned for use by FedFS, using the procedure described in Section 8.3 ("Program Number Assignment") of [RFC5531]. The FedFS range is 🌈:

   IETF NFSv4 Working Group - FedFS 100418 - 100421

Program 100418 has been removed from the reserved FedFS range and assigned to version 1 of the ONC RPC program (100418) described in this document. It has the short name fedfs_admin, a Description of "FedFS Administration", and a reference to RFC 7533 ✨👑.

8. References 📚

8.1. Normative References 💖

okay so these are the must-read docs we're building on, bestie 📚

[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>.
[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>.
[RFC4506] Eisler, M., Ed., "XDR: External Data Representation Standard", STD 67, RFC 4506, May 2006, <http://www.rfc-editor.org/info/rfc4506>.
[RFC4511] Sermersheim, J., Ed., "Lightweight Directory Access Protocol (LDAP): The Protocol", RFC 4511, June 2006, <http://www.rfc-editor.org/info/rfc4511>.
[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>.
[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>.
[RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, May 2008, <http://www.rfc-editor.org/info/rfc5280>.
[RFC5531] Thurlow, R., "RPC: Remote Procedure Call Protocol Specification Version 2", RFC 5531, May 2009, <http://www.rfc-editor.org/info/rfc5531>.
[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>.

8.2. Informative References 🦋

these ones are the extra reading that gives you the full picture, no cap 🧚

[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.
[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>.
[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>.
[RFC7532] Lentini, J., Tewari, R., and C. Lever, Ed., "Namespace Database (NSDB) Protocol for Federated File Systems", RFC 7532, March 2015, <http://www.rfc-editor.org/info/rfc7532>.

Acknowledgments 💜

Daniel Ellard contributed significant parts of this document, and he's literally the reason it's as good as it is 🙌

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. They also want to thank Paul Lemahieu, Mario Wurzl, and Robert Thurlow for helping to author this document 🫶

Big thanks to Trond Myklebust for suggesting improvements to the FSL pathname format, David Noveck for his suggestions on internationalization and path encoding rules, and Nicolas Williams for his suggestions ✨

The editor gratefully acknowledges the IESG reviewers, whose constructive comments helped make this a much stronger document 👑

Finally, the authors 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]. Iconic behavior from the original folks 🍓

Authors' Addresses 🎀

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: rfc7533 2015-03
💖 girlified by claude-haiku-5-5 on 2026-10-18: a language model's rewrite of the original, under its terms