fedfs-domainroot (8) - Linux Manuals

fedfs-domainroot: set up FedFS domain root infrastructure

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 administrators 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 directory 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 component 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 directory 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 argument.

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 authoritative 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 recommend 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

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 [at] oracle.com>