
			Linux FedFs Implementation

Author: Chuck Lever <chuck.lever@oracle.com>

This package contains an implementation of the Federated Filesystem
(FedFS) proposed standard for Linux.  For an introduction to FedFS,
see RFC 5716, or read the fedfs(7) man page provided in the doc/man
directory.

This package is copyright 2010 and 2011, Oracle. It's use is covered
by version 2 of the GNU General Public License.  See the COPYING file
for details.  A few parts are also covered by the IETF's code license,
which is a simplified BSD license that is compatible with GPLv2.


Build instructions
----- ------------

If you are unfamiliar with FedFS, review RFC 5716 and fedfs(7).  Once
you are satisfied that you understand what is being built, go to the
top-level directory and type:

  ./autogen.sh
  ./configure

You may need to install a few -devel packages here.

  make all

If you are interested in installing the FedFS executables, type:

  sudo make install

However, for testing, they should work when run directly from the
build tree.


Note well:

The FedFS protocol draft specifies the FedFS schema in LDIF format,
compliant to RFC 2489.  LDAP servers which are descended from the
iPlanet Directory Server (such as 389-ds) accept schema files which
strictly adhere to an older standard, RFC 2252.

This package provides both versions of the FedFS schema.  Choose
either fedfs.schema (for OpenLDAP-derived LDAP servers) or
fedfs-schema.ldif (for iPlanet-derived servers), and copy that file
to the schema repository your server uses.  For example, 389-ds uses
/etc/dirsrv/schema to hold schema files that should be used when
creating new slapd instances.

The fedfs-utils/doc/ldap Makefile does not contain an install target
for these schema files, since the install destination depends on which
flavor of LDAP server is in use.  The LDAP server may even be on
another host.


Interesting top-level build targets
----------- --------- ----- -------

  all:		Build the fedfs-utils world

  install:	Install client and server executables and man pages
		on the local system

  clean:	Clean up object files and generated source

  distcheck:    Run a complete install to check that all is in order

  dist:		Make a tarball for distribution

  distclean:	Wipe everything built by ./configure


Specific FedFS roles
-------- ----- -----

There are several different roles a host can play when participating
in a FedFS domain:

  NSDB			LDAP server that contains FedFS domain
			information

  FedFS file server	stores data accessible via a FedFS
			domain name space

  FedFS client		accesses data in FedFS domain name
			spaces

  FedFS admin client	manages FedFS domain information

Any host can play any or all of these roles.  This section provides
a rough description of how hosts playing each of these roles might be
configured.


NSDB

  o Choose an LDAP server package and install it

  o Install the FedFS schema in the LDAP servers' schema directory

  o If this is a new LDAP server, create a slapd instance

  o Optionally create an X.509 certificate for the LDAP server and
    install it on the server

  o Use nsdbparams to add connection parameters for the new NSDB on
    your NSDB admin client host; optionally install the certificate you
    created

  o Set up an NCE


FedFS file server

  o Install various distribution pre-requisites, such as libtirpc,
    an LDAP client library, and libsqlite3

  o Install kernel 3.2 or later, and configure NFSD

  o Install junction resolution plug-in

  o Install nfs-utils 1.2.6 or later

  o Install the nfsref program

  o Set up a fedfs user ID and group ID

  o Create /var/lib/fedfs and set its user and group to the fedfs
    user and group ID

  o Add a line containing "fedfs_admin	100418" to /etc/rpc

  o (Eventually RPCGSS configuration will go here)

  o Use nsdbparams to add connection parameters and X.509 certificates
    for NSDBs to the local NSDB connection parameter database

  o Install fedfsd and a fedfsd init script


FedFS client

  o Install /usr/sbin/fedfs-map-nfs4

  o Create a local /nfs4 directory

  o Install and configure autofs

  o Add an entry to the master map (usually /etc/auto.master) for
    the /nfs4 directory and restart autofs


FedFS admin client

  o Install various distribution pre-requisites, such as libtirpc,
    an LDAP client library, and libsqlite3

  o Set up a fedfs user ID and group ID

  o Create /var/lib/fedfs and set its user and group to the fedfs
    user and group ID

  o Add a line containing "fedfs_admin	100418" to /etc/rpc

  o (Eventually RPCGSS configuration will go here)

  o Use nsdbparams to add connection parameters and X.509 certificates
    for NSDBs to the local NSDB connection parameter database

  o Install the nsdbc and fedfsc clients


In addition to these tasks, you should choose one of the FedFS-enabled
file servers on which to host the domain root directory, and set up a
DNS SRV record to allow FedFS file system clients to find it.


Configuring the junction resolution plug-in

By default, the junction resolution plug-in library is installed in
/usr/local/lib.  Mountd's junction plug-in support searches the default
library path for this plug-in, but mountd's library path does not
normally contain /usr/local/lib.

There are several options:

  o Specify an LD_LIBRARY_PATH when starting mountd that includes
    /usr/local/lib,

  o Move the installed plug-in files to a directory that is included
    in mountd's existing library path, or

  o Use the --libdir= command line option on fedfs-utils's ./configure
    to change the installed location of the plug-in library.
