FEDFS-DOMAINROOT(8) System Manager's Manual FEDFS-DOMAINROOT(8)
NAME
fedfs-domainroot - set up FedFS domain root infrastructure
SYNOPSIS
fedfs-domainroot [-h, --help] [--version]
fedfs-domainroot [--silent] [--statedir= statedir] add domainname
fedfs-domainroot [--silent] [--statedir= statedir] remove domainname [--force]
fedfs-domainroot [--silent] [--statedir= statedir] status
fedfs-domainroot [--silent] [--statedir= statedir] clean [--force]
INTRODUCTION
RFC 5716 introduces the Federated File System (FedFS, for short). FedFS is an extensible standardized mechanism by which system adminis-
trators construct a coherent namespace across multiple file servers using file system referrals. For further details, see fedfs(7).
The top directory of a FedFS domain namespace is known as a domain root directory. FedFS-enabled clients discover the fileserver that
exports a FedFS domain's root directory using a DNS SRV query. Using a well-known export path, clients then mount the domain root direc-
tory on that fileserver in the normal fashion.
After a filesystem client mounts a domain's root directory, applications on that client descend into the domain's name space starting in
that directory, and are directed transparently to exports on other fileservers.
Further information about domain roots is available in fedfs(7).
DESCRIPTION
A single fileserver may host domain root directories for one or more FedFS domains. The fedfs-domainroot(8) command is a convenient way to
securely manage domain root exports on a Linux NFS fileserver. FedFS itself is agnostic about the underlying file-access protocol, but the
fedfs-domainroot(8) command supports only NFS at this time.
FedFS domain root directories are exported using a standard well-known pathname to make it simple for clients to find them. The first com-
ponent of the domain root's export pathname is always /.domainroot. The second component is a FedFS domain name.
For instance, the export pathname of the domain root of the example.net FedFS domain is /.domainroot/example.net.
Operation
The add subcommand creates a directory under /var/lib/fedfs/domainroots where the contents of the domain root directory reside. A direc-
tory is also set up under /.domainroot for each doman root directory. fedfs-domainroot(8) bind-mounts the domain root directory under
/var/lib/fedfs/domainroots, then exports the directory under /.domainroot.
In this way, each domain root directory is exported via a well-known pathname, and can have its own export settings separate from other
domain root directories, including security settings and client and network designations. These can be modified by editing /etc/exports
after the domain root export is created.
The fedfs-domainroot(8) command must run as root in order to create and remove NFS exports and entries in /etc/fstab.
Subcommands
Valid fedfs-domainroot(8) subcommands are:
clean Remove the /.domainroot directory and other infrastructure (as long as it is empty). The user is asked to confirm before action is
taken.
By default, this process stops when a step encounters an error. Adding the --force option forces the process to try each step even
if an error occurs, and bypasses the confirmation request.
status Display the status of the domain root infrastructure on the local system. This includes whether NFSD is running, and what domain
root directories are currently configured and exported. This subcommand takes no arguments.
add Create a new FedFS domain root directory under /.domainroot and export it. This subcommand takes a FedFS domain name as an argu-
ment.
remove Remove an existing FedFS domain root directory from /.domainroot. This subcommand takes a FedFS domain name as an argument. The
user is asked to confirm before action is taken.
By default, this process stops when a step encounters an error. Adding the --force option forces the process to try each step even
if an error occurs, and bypasses the confirmation request.
Command line options
The following options are specified before the subcommand on the command line.
-h, --help
Display usage and copyright information, then exit.
--version
Display fedfs-utils version information, then exit.
--silent
Process quietly.
--statedir=state-directory
Find FedFS domain root directories on the local system in the domainroots subdirectory of the specified directory. By default, the
state directory is /var/lib/fedfs.
EXIT CODES
The fedfs-domainroot(8) command returns one of two values upon exit.
0 The requested subcommand succeeded.
1 The requested subcommand failed.
EXAMPLES
Suppose you are the FedFS administrator of the example.net FedFS domain. After you have chosen a reliable NFS fileserver to serve your
FedFS domain root directory, log in on that fileserver as root and ensure that NFSD is running.
To create a new FedFS domain root for the example.net domain, use:
# fedfs-domainroot --silent add example.net
Added domain root for FedFS domain "example.net"
#
To populate the new domain root, change your current directory to /.domainroot/example.net, then add junctions with the nfsref(8) command
on the fileserver.
You can list the domain roots that are currently exported by your fileserver with:
# fedfs-domainroot --silent status
FedFS domain roots:
example.net is exported with options
*(ro,subtree_check,mp,insecure,sec=sys:none)
#
When you want to remove this domain root (say, because you have moved it to another fileserver), remove it's contents, then use:
# fedfs-domainroot remove example.net
Removed domain root for FedFS domain "example.net"
#
DOMAIN ROOT DISCOVERY
To enable discovery of new domain roots by FedFS-enabled file-access clients, a DNS SRV record must be added to an appropriate authorita-
tive DNS server.
If you created your domain root on the fileserver named foo.example.net, a record for the above domain root should be added to the DNS
server authoritative for the example.net domain. Such a record might look like
_nfs-domainroot._tcp IN SRV 0 0 2049 foo.example.net.
Adding DNS SRV records is outside the scope of the fedfs-domainroot(8) command. Consult with your network administrator for details on how
to add appropriate DNS SRV records for your FedFS domain root.
SECURITY
FedFS domain root exports created by fedfs-domainroot(8) are exported with *(ro,insecure,subtree_check,sec=sys:none). FedFS standards rec-
ommend that FedFS domain root directories should be globally readable. Specific access restrictions typically occur lower in a domain's
name space.
However, fileserver administrators can alter a domain root export's security settings by editing a domain root export's entry in
/etc/exports, and then refreshing the kernel's export cache with exportfs -r.
For example, if the domain root fileserver has Kerberos configured, an administrator might change a domain root export's sec= option to
sec=krb5p:krb5i:krb5:sys:none. Or, to restrict the range of clients that can access the domain root, an administrator might replace the
leading * with a specific netgroup or IP network designation.
It is recommended to keep the subtree_check export option. Refer to exports(5) for details.
FILES
/var/lib/fedfs/domainroots
directory containing domain root directories
/.domainroot
directory containing domain root exports
SEE ALSO
fedfs(7), nfsref(8), rpc.fedfsd(8), exportfs(8), exports(5)
RFC 6641 for the specification of FedFS DNS SRV records
COLOPHON
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.
AUTHOR
Chuck Lever <chuck.lever@oracle.com>
3 February 2014 FEDFS-DOMAINROOT(8)