fedfs man page

fedfs — The Linux Federated File System implementation


RFC 5716 introduces the Federated File System (FedFS, for short). FedFS is an extensible standardized mechanism by which system administrators construct a coherent namespace across multiple fileservers using file system referrals.

A file system referral is like a symbolic link to another file system share, but it is not visible to applications. It behaves like an automounted directory where a mount operation is performed when an application first accesses that directory.

Today, file system referral mechanisms exist in several standard network file system protocols. Because FedFS uses a mechanism already built in to standard network protocols, using it does not require any change to file system protocols or file-access client implementations.

A sideband protocol, such as NIS, is also unnecessary. File-access clients automatically share a common view of the network file system namespace with no need for individual configuration on each client.

Currently, the Linux FedFS implementation supports only NFS version 4 referrals. More on NFS version 4 referrals can be found in RFC 5661. FedFS may support other network file system protocols in the future.

Fedfs Domain Operation

A file system referral whose target is managed by FedFS is called a FedFS junction. Junctions join separate fileserver shares into a single coherent FedFS namespace. On FedFS-enabled Linux fileservers, the rpc.fedfsd(8) daemon and the nfsref(5) command create and remove FedFS junctions.

An independently administered FedFS namespace is referred to as a FedFS domain. FedFS domains are file namespaces only. They do not represent authentication or ID-mapping realms, for example. FedFS-enabled file-access clients and fileservers are not members of a particular FedFS domain and do not have a priori knowledge of what FedFS domains exist.

The top-level directory of a FedFS domain is referred to as its domain root. Domain roots typically contain nothing but FedFS junctions and a few other directories. Useful data is contained in other shares which file-access clients discover by following FedFS junctions in the domain root directory.

Although FedFS junctions are stored on fileservers, they are lightweight objects that contain little actual data. The bulk of FedFS junction information in a FedFS domain is stored on an LDAP server. LDAP servers that store FedFS information are known as namespace databases, or NSDBs, for short. Any standard LDAP server can become an NSDB if it knows the FedFS schema (the definitions of FedFS record types).


FedFS groups a set of directories in a server's physical file system namespace into a single administrative unit called a fileset. For NFS, a whole share might be considered a fileset. A FedFS domain consists of one or more filesets, a domain root, and junction information stored on an NSDB node.

To function as a FedFS fileset, a set of directories must have a name unique in a FedFS domain, and a set of locations where the file data is stored.

A FedFS fileset name is a UUID and an NSDB domainname and port. This information is also maintained in an LDAP record on the NSDB node.

A FedFS fileset location is an LDAP record that describes the location (the fileserver where it resides, and its export path) of a copy of a fileset's data. These records are children of the fileset name record for this fileset.

A fileset can have multiple replicas. Such a fileset has one FedFS fileset name, and each replica of the fileset has an individual FedFS fileset location record.

A FedFS junction contains only a FedFS fileset name. A fileserver resolves a FedFS junction by performing an LDAP query on the NSDB node named in the junction, using the UUID named in the junction. The NSDB node returns location information stored in FedFS fileset location records for that FedFS fileset name. The fileserver returns this location information to file-access clients it servers via a file system referral.

On Linux NFS fileservers, rpc.mountd(8) is the gateway through which the in-kernel NFS server performs FedFS junction resolution.

Discovering domain roots

As with other FedFS filesets, copies of a domain root can exist on multiple fileservers. These copies are known as domain root replicas.

Rather than using junctions and information in an NSDB node, FedFS-enabled file-access clients locate a domain's root by looking for DNS SRV records that advertise fileservers exporting domain root replicas.

Such clients typically mount FedFS domain roots in a standard place so that files residing in a FedFS domain appear at the same location in the file namespace on all file-access clients. By convention, the top of the global FedFS namespace looks like this:


where fstype specifies a network file system protocol to use, and domainname specifies a FedFS domain. Currently, the Linux FedFS implementation recognizes only nfs4 as a valid fstype.

Globally Useful Names

On FedFS-enabled Linux file-access clients, the automounter (via a program map) or the mount.fedfs(8) command find and mount the root of a FedFS domain.

Typically, file-access clients mount the FedFS namespace so that FedFS pathnames appear the same on all clients. Such pathnames are referred to as globally useful names, since a globally useful name refers to exactly the same file object on every file-access client in a FedFS domain.

For example, the FedFS globally useful name /nfs4/example.net would be mounted on a local directory called /nfs4/example.net on all file-access clients, so that applications have the same view of the example.net domain namespace on all FedFS-enabled file-access clients.

The Linux mount.fedfs(8) command can attach anywhere in a file-access client's local file namespace any directory in the FedFS namespace that client has permission to access. This can be useful to ensure local namespace compatibility in some cases, or hide parts of the FedFS namespace for security purposes.

However, it breaks cross-platform application interoperability by presenting applications with multiple pathnames to the same file object. Therefore it should be avoided.


Each host in a FedFS domain plays one or more of the following roles, each of which have different security requirements.

NSDB node

LDAP server that contains FedFS domain information

FedFS fileserver

stores data accessible via a FedFS domain name space

FedFS file-access client

accesses data in FedFS domain name spaces

FedFS admin client

manages FedFS domain information

The Linux FedFS implementation provides administrative tools to manage FedFS fileset name and location records on an NSDB node. Junction resolution uses anonymous LDAP search requests, and administration takes place via authenticated LDAP modification requests.

Fileservers and administrative clients use plaintext or TLS-secured transports to perform junction lookups and administrative requests. The Linux FedFS implementation provides tools for managing x.509 certificates required for LDAP over TLS.

FedFS junction objects are created on fileservers by a side-band RPC protocol called the FedFS ADMIN protocol. This protocol is separate from network file system protocols. This allows FedFS to operate without modification to network file system protocols. The protocol uses RPCSEC GSS to secure administrative requests.

Since two separate protocols are involved when administering junctions and filesets, junctions are created on fileservers and registered with the domain's NSDB node in two separate steps.

See Also

nsdb-parameters(7), nsdbparams(8), fedfs-map-nfs4(8), mount.fedfs(8), rpc.fedfsd(8), rpc.mountd(8), fedfs-create-junction(8), fedfs-create-replication(8), fedfs-delete-junction(8), fedfs-delete-replication(8), fedfs-get-limited-nsdb-params(8), fedfs-get-nsdb-params(8), fedfs-lookup-junction(8), fedfs-lookup-replication(8), fedfs-null(8), fedfs-set-nsdb-params(8), nsdb-simple-nce(8), nsdb-annotate(8), nsdb-create-fsl(8), nsdb-create-fsn(8), nsdb-update-nci(8), nsdb-delete-fsl(8), nsdb-delete-fsn(8), nsdb-remove-nci(8), nsdb-describe(8), nsdb-list(8), nsdb-nces(8), nsdb-resolve-fsn(8), nsdb-update-fsl(8)

RFC 4510 for an introduction to LDAP

RFC 5661 for a description of NFS version 4 referrals

RFC 5716 for FedFS requirements and overview


This page is part of the fedfs-utils package. A description of the project and information about reporting bugs can be found at http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject.


Chuck Lever <chuck.lever@oracle.com>

Referenced By

fedfs-create-junction(8), fedfs-create-replication(8), fedfs-delete-junction(8), fedfs-delete-replication(8), fedfs-domainroot(8), fedfs-get-limited-nsdb-params(8), fedfs-get-nsdb-params(8), fedfs-lookup-junction(8), fedfs-lookup-replication(8), fedfs-map-nfs4(8), fedfs-null(8), fedfs-set-nsdb-params(8), mount.fedfs(8), nfsref(8), nsdb-annotate(8), nsdb-create-fsl(8), nsdb-create-fsn(8), nsdb-delete-fsl(8), nsdb-delete-fsn(8), nsdb-delete-nsdb(8), nsdb-describe(8), nsdb-jumpstart(8), nsdb-list(8), nsdb-nces(8), nsdb-parameters(7), nsdbparams(8), nsdb-remove-nci(8), nsdb-resolve-fsn(8), nsdb-simple-nce(8), nsdb-update-fsl(8), nsdb-update-nci(8), rpc.fedfsd(8).

3 February 2014