Administration Protocol for Federated File Systems
Extracted elements (26)
Administrative paths used by FEDFS procedures (FEDFS_PATH_SYS) are implementation-dependent and need not appear in the federated namespace or be relative to the server pseudo-root. The global namespace and server-local namespace are intentionally decoupled, allowing flexible internal server organization.
FEDFS_CREATE_JUNCTION does not require the target fileset to exist at junction creation time; if the target fileset is missing, the junction is still created and an NFS client discovers the absence only upon traversal. This decouples namespace construction from fileset availability.
FEDFS_GET_LIMITED_NSDB_PARAMS exists to expose only the FedFsConnectionSec security type (not the full connection parameters including potentially sensitive TLS certificate material) to less-privileged callers. This allows checking what security mechanism is in use without revealing the trust anchor certificate.
FedFS status code names and meanings are inspired by NFSv4 (RFC 7530) counterparts (e.g., FEDFS_ERR_ACCESS mirrors NFS4ERR_ACCESS), but their numeric values are different and must not be confused or aliased between protocols.
Two FedFsNsdbNames are equal if their hostname and port fields match. Port value 0 always matches port 389 (standard LDAP); thus (nsdb.example.com, 0) equals (nsdb.example.com, 389) but not (nsdb.example.com, 1066) or (nsdb.foo.example.com, 389).
FEDFS_CREATE_REPLICATION sets a fileset-wide replication FSN used to satisfy NFSv4 fs_locations or fs_locations_info requests when no junction is being accessed. The same FSN value SHOULD be associated with all replicas of a file system, requiring FEDFS_CREATE_REPLICATION to be applied to all replicas.
FEDFS_SET_NSDB_PARAMS: after a successful set, the new connection parameters SHOULD be used for all subsequent LDAP connections to the given NSDB. The connection parameters SHOULD be durable across fileserver reboots. If the caller lacks sufficient permissions, FEDFS_ERR_ACCESS MUST be returned.
FedFsNsdbName MUST NOT contain a network address (IPv4 or IPv6); it must use a fully qualified domain name. This preserves the immutability of FSNs, which include the NSDB name as an attribute.
FedFsUuid MUST be formatted in network byte order. FedFsPathName MUST NOT contain any zero-length components. Component names for NFSv4 paths MUST be prepared using the NFSv4 internationalization rules (RFC 7530 Section 12) before encoding.
Fileservers participating as 'internal' nodes in the federated namespace MUST implement FEDFS_NULL, FEDFS_CREATE_JUNCTION, FEDFS_DELETE_JUNCTION, FEDFS_LOOKUP_JUNCTION, FEDFS_SET_NSDB_PARAMS, FEDFS_GET_NSDB_PARAMS, and FEDFS_GET_LIMITED_NSDB_PARAMS. They SHOULD additionally implement FEDFS_CREATE_REPLICATION, FEDFS_DELETE_REPLICATION, and FEDFS_LOOKUP_REPLICATION.
For FEDFS_CREATE_JUNCTION and FEDFS_DELETE_JUNCTION, the path MUST NOT contain a junction except (for delete/lookup) as the final component. If any non-final component is a junction, the operation MUST fail with FEDFS_ERR_NOTLOCAL. Path traversal MUST remain within the server-local namespace even if symbolic links are present.
For FEDFS_LOOKUP_JUNCTION with resolve=FEDFS_RESOLVE_NONE, the fileserver MUST NOT attempt to resolve the FSN and returns a zero-length fsl list. With FEDFS_RESOLVE_CACHE, the server MUST attempt cache-only resolution and MUST NOT contact the NSDB. With FEDFS_RESOLVE_NSDB, the server MUST contact the NSDB and MUST NOT use cached information.
Operations that modify the state of a replicated fileset MUST result in the update of all replicas in a consistent manner. If replicas are unavailable, the operation MAY succeed, but changes MUST be applied before the unavailable replicas are brought back online.
The association between path and FSN created by FEDFS_CREATE_JUNCTION MUST be durable before the operation returns successfully; upon success the junction is immediately accessible. If the last path component is already a junction, FEDFS_ERR_EXIST MUST be returned even if the requested junction is identical to the existing one.
When FEDFS_SEC_TLS is configured, the fileserver MUST use StartTLS (RFC 4513) for all connections to that NSDB, and MUST use the DER-encoded X.509v3 certificate in secData as the trust anchor to validate the NSDB's TLS server certificate chain. These trust anchors MUST only be used for the NSDB service, not as system-wide trust anchors.
The FedFS administration protocol is conveyed over ONC RPC (RFC 5531) with parameters and return values encoded in XDR (RFC 4506). The protocol is defined as program FEDFS_PROG (100418), version FEDFS_V1 (1), with ten defined procedures.
ONC RPC program number 100418 is assigned from the IETF NFSv4 Working Group FedFS range (100418–100421) to version 1 of the FedFS administration protocol, with short name 'fedfs_admin' and description 'FedFS Administration', as specified in RFC 7533.
An Access Control Service is strongly RECOMMENDED to restrict access to the FedFS administration configuration data, preventing namespace corruption and protecting NSDB communication parameters. When TLS trust anchors are provisioned via FEDFS_SET_NSDB_PARAMS, RPCSEC_GSS with data integrity SHOULD be used and access restricted to domain administrators.
Fileservers supporting the FedFS administration protocol MUST support RPCSEC_GSS (RFC 2203). Both clients and servers MUST support RPCSEC_GSS integrity and authentication services. Servers MUST support RPCSEC_GSS privacy; clients SHOULD support it. When RPCSEC_GSS is in use, data integrity SHOULD be employed.
TLS trust anchor certificates provisioned through FedFsNsdbParams secData MUST only be used for authenticating the NSDB service, not installed as system-wide trust anchors for other services. This prevents provisioned credentials from inadvertently expanding trust scope beyond the federation.
FedFsFsn (Fileset Name) is a struct combining a FedFsUuid (fsnUuid) with a FedFsNsdbName (nsdbName), providing a globally unique, platform-independent fileset identifier. FedFsFsl (Fileset Location) is a union on FedFsFslType; the only defined type, FEDFS_NFS_FSL, contains fslUuid, port, hostname, and a FedFsPathName path.
FedFsNsdbName encodes an NSDB's network location as a (hostname, port) pair: hostname is a variable-length UTF-8 string in FQDN DNS notation; port is an unsigned int in the range 0–65535 where 0 means the standard LDAP port 389.
FedFsNsdbParams is a union on FedFsConnectionSec: FEDFS_SEC_NONE (0) carries no secData; FEDFS_SEC_TLS (1) carries an opaque secData<> containing an X.509v3 root certificate in binary DER format used as the TLS trust anchor for the NSDB connection.
FedFsPath is a union on FedFsPathType: FEDFS_PATH_SYS (0) is an implementation-dependent administrative pathname; FEDFS_PATH_NFS (1) is a pathname in the NFSv4 server's single-server namespace. FedFsPathName is a variable-length array of UTF-8 FedFsPathComponent strings; the path '/' MUST be encoded as a zero-element array.
FedFsStatus is an XDR enum with 38 values (0–37) encoding operation results, including NSDB connectivity errors (FEDFS_ERR_NSDB_ROUTE through FEDFS_ERR_NSDB_FAULT), LDAP referral errors, cache errors, and path errors. Numeric values differ from analogous NFSv4 status codes even where names are similar.
FedFsUuid is a 16-byte opaque field encoding a version 4 UUID (RFC 4122) in network byte order. It is used as both the fileset name UUID (fsnUuid in FedFsFsn) and the fileset location UUID (fslUuid in FedFsNfsFsl).