From FedoraProject

< Features
Revision as of 04:28, 29 July 2012 by Iankent (Talk | contribs)

Jump to: navigation, search




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 file servers using file system referrals.


  • Name: Ian Kent
  • Email: ikent@redhat.com

Current status

  • Targeted release: Fedora 18
  • Last updated: Jul 24, 2012
  • Percentage of completion: 100%

Detailed Description

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 file servers 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 new file system mount is done when an application first accesses that directory. The arguments of the mount operation are controlled by information returned by the file server.

Today, file system referral mechanisms exist in several network file system protocols. FedFS provides its namespace features by leveraging referral mechanisms already built in to network file system protocols. Thus no change to file system protocols or clients is required.

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

Benefit to Fedora

See detailed description. As this is an emerging standard, we want Fedora to be one of the first operating systems to support it.

Chuck Lever also points out that fedfs-utils is part of a larger, ongoing effort to build out storage administration features on Linux file servers. This includes, to name but a few:

  • The ability to manage NFS referrals either via FedFS or via a simple command line tool on file servers
  • Support for SMB2 in a FedFS framework
  • Support for NFSv4.1's fs_locations_info attribute
  • Client-side support for NFSv4 migration with transparent state migration
  • Support for transparent NFS client access to replicated file sets


Much of the work for this has already been done. Chuck Lever of Oracle has done an implementation of the required userspace tools for this, and a Fedora package of release 0.8.0 has been built. We'll probably also need to do some documentation and/or articles describing how to set up both the client and server for FedFS.

The upstream project website for this is here:


It contains license information, presentation slides, the FedFS LDAP schema, and a project roadmap.

Fedfs is, in many ways, an addition of automount functionality along the line of something that I believe (as the autofs maintainer both upstream and here in Fedora) has been needed for a long time. That is a distributed autofs mount map resource manager and while fedfs isn't quite what I envisioned for autofs the functionality it provides is fairly close. Just how far integration with autofs will go isn't clear yet.

At this stage the fedfs package cotains an autofs program map that is used to provide access to the namespace and that is sufficient to start with. An improvement to autofs that I plan on doing is to add native support to autofs for fedfs in order to provide earier discovery and access to the available fedfs namespaces.

How To Test

Simple example of basic FedFS operation

Assume a test DNS server has been setup for a DNS domain autofs.test (in this case both were setup on zeus.autofs.test) and that the hosts perseus.autofs.test and zeus.autofs.test map to vaild addresses. Also assume that resolve.conf has been amended to use this DNS server.

Also assume we have an LDAP instance that has a naming context of "dc=autofs,dc=test" that is functional on the server and the client can perfom queries.

Further assume that the services used are running. Namely, LDAP, FedFS daemon and NFS services on zeus.autofs.test, and FedFS daemon and autofs services on zeus.autofs.test.

Finally assume that packages fedfs-utils-common, fedfs-utils-nsdbparams, fedfs-utils-server and fedfs-utils-client are installed on perseus.autofs.test. And that fedfs-utils-common, fedfs-utils-server and an nfs-utils built with fedfs-utils-devel installed are installed on zeus.autofs.test.

The DNS and LDAP (OpenLDAP) configuration files can be provided for reference and step by step instructions can be done, if required. But it is assumed that someone wishing to test FedFS will be able to adapt the procedures below to an existing test environment.

What want to setup perseus.autofs.test to provide the domain root, be able to use FedFS to mount the domain root, and to setup and use a FedFS juntion to access an export on zeus.autofs.test upon access to a directory within the domain root. And lastly, setup autofs to use the FedFS program map to mount the root of the domain.

Setup an NSDB

1. Set parameters for NSDB connections:
        # nsdbparams(8) is used to set NSDB connection parameters
        nsdbparams update -e "o=fedfs,dc=autofs,dc=test" \
                          -D "cn=Manager,dc=autofs,dc=test" \

2. Add FedFS schema to LDAP server config (which can be found
   in the FedFS common package docunentation directory).

3. Add a FedFS naming context to LDAP server.
        ldapadd -v -x \
                -h zeus.autofs.test \
                -f init.ldif \
                -D "cn=Manager,dc=autofs,dc=test" -W
   where init.ldif contains:
     dn: o=fedfs,dc=autofs,dc=test
     objectclass: organization
     objectClass: top
     o: fedfs

4. Add NCI (NSDB Container information) attributes to the
   naming context LDAP entry:
        nsdb-update-nci -l zeus.autofs.test \
                -D "cn=Manager,dc=autofs,dc=test" \
                -e "o=fedfs,dc=autofs,dc=test"

<!-- This does not need to be a full-fledged document.  Describe the dimensions of tests that this feature is expected to pass when it is done.  If it needs to be tested with different hardware or software configurations, indicate them.  The more specific you can be, the better the community testing can be. 

Remember that you are writing this how to for interested testers to use to check out your feature - documenting what you do for testing is OK, but it's much better to document what *I* can do to test your feature.

A good "how to test" should answer these four questions:

0. What special hardware / data / etc. is needed (if any)?
1. How do I prepare my system to test this feature? What packages
need to be installed, config files edited, etc.?
2. What specific actions do I perform to check that the feature is
working like it's supposed to?
3. What are the expected results of those actions?

== User Experience ==
<!-- If this feature is noticeable by its target audience, how will their experiences change as a result?  Describe what they will see or notice. -->
The casual Fedora user won't see any changes with this. This should only change the experience for someone who makes the effort to set up and use FedFS.

== Dependencies ==
<!-- What other packages (RPMs) depend on this package?  Are there changes outside the developers' control on which completion of this feature depends?  In other words, completion of another feature owned by someone else and might cause you to not be able to finish on time or that you would need to coordinate?  Other upstream projects like the kernel (if this is not a kernel feature)? -->
There are some kernel patches required which are fairly modest in scope and have been included in the upstream kernel since version 3.2.

There are also some changes needed to nfs-utils (specifically mountd) to allow it to process junctions. The change to nfs-utils required by version 0.8.0 has been done although nfs-utils will need to be rebuilt to recognise that the fedfs-utils plugin is now present.

Additionally, LDAP servers need to have the FedFS LDAP schema installed. The schema is not yet included in Openldap so users will need to manually add the schema which is included in the package fedfs-utils-common and placed in docs directory.

/etc/rpc needs to be updated to include the IANA-assigned fedfs RPC program number which was added in glibc-2.15-12, available since Fedora 17.

== Contingency Plan ==
<!-- If you cannot complete your feature by the final development freeze, what is the backup plan?  This might be as simple as "None necessary, revert to previous release behaviour."  Or it might not.  If you feature is not completed in time we want to assure others that other parts of Fedora will not be in jeopardy.  -->
If this package isn't approved for inclusion, we simply won't ship fedfs-utils.

== Documentation ==
<!-- Is there upstream documentation on this feature, or notes you have written yourself?  Link to that material here so other interested developers can get involved. -->
The package has a fairly comprehensive set of manpages, but we may also need to create some other "How-To" documentation.

== Release Notes ==
<!-- The Fedora Release Notes inform end-users about what is new in the release.  Examples of past release notes are here: http://docs.fedoraproject.org/release-notes/ -->
<!-- The release notes also help users know how to deal with platform changes such as ABIs/APIs, configuration or data file formats, or upgrade concerns.  If there are any such changes involved in this feature, indicate them here.  You can also link to upstream documentation if it satisfies this need.  This information forms the basis of the release notes edited by the documentation team and shipped with the release. -->
The code provided in this package is a technology preview. The intent is to provide a full and supported Linux FedFS client and server implementation
based on this code. Programming and user interfaces may change significantly for the next few releases.

The components in this package are used for managing file system referrals in order to create a global network file system namespace. Installable
components include:

* An automounter program map to manage the FedFS domain namespace on FedFS-enabled clients.
* A mount command to mount parts of a FedFS domain namespace.
* A plug-in library that allows programs outside of FedFS to resolve junctions on local file systems.
* An ONC RPC service daemon that runs on file servers enabling the management by remote FedFS ADMIN clients of FedFS junctions.
* A tool called "nfsref" to manage local junctions without requiring fedfsd.
* A set of command-line clients that can access fedfsd instances on remote file servers.
* A set of command-line clients that can manage FedFS entries on an LDAP server acting as a FedFS NSDB.
* A tool to manage NSDB connection parameters on the local host.
* An LDIF format schema to enable an LDAP server to support FedFS objects.

For more information refer to the [http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject FedFS project page] and the [http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsDocs FedFS Documentation page].

== Comments and Discussion ==
* See [[Talk:Features/FedFS]]  <!-- This adds a link to the "discussion" tab associated with your page.  This provides the ability to have ongoing comments or conversation without bogging down the main feature page -->

<!-- When your feature page is completed and ready for review -->
<!-- remove Category:FeaturePageIncomplete and change it to Category:FeatureReadyForWrangler -->
<!-- After review, the feature wrangler will move your page to Category:FeatureReadyForFesco... if it still needs more work it will move back to Category:FeaturePageIncomplete-->
<!-- A pretty picture of the page category usage is at: https://fedoraproject.org/wiki/Features/Policy/Process -->