nfsref (8) - Linux Manuals

nfsref: manage NFS referrals

NAME

nfsref - manage NFS referrals

SYNOPSIS

nfsref [-?d] [-t type] add pathname server export [ server export ... ]

nfsref [-?d] [-t type] remove pathname

nfsref [-?d] [-t type] lookup pathname

INTRODUCTION

NFS version 4 introduces the concept of file system referrals to NFS. A file system referral is like a symbolic link on a file server to another file system share, possibly on another file server. On an NFS client, a referral behaves like an automounted directory. The client, under the server's direction, mounts a new NFS export automatically when an application first accesses that directory.

Referrals are typically used to construct a single file name space across multiple file servers. Because file servers control the shape of the name space, no client configuration is required, and all clients see the same referral information.

The Linux NFS server supports NFS version 4 referrals. Administrators can specify the refer= export option in /etc/exports to configure a list of exports from which the client can choose. See exports(5) for details.

The nfsref(8) command provides an alternate way to configure NFS referrals. This command stores referral information as metadata within a leaf directory in an exported file system. The metadata it stores can contain one of two types of information:

A list of Fileset Locations

A set of server name and export path pairs which are returned verbatim to clients during an NFS referral event. This is known as an NFS basic junction.

A Fileset Name

The name of an LDAP record which contains information to return to clients during an NFS referral event. This is known as a FedFS junction.

A directory can hold either an NFS basic junction or a FedFS junction, but not both. When a directory acts as a junction, its regular contents remain, but are no longer visible to NFS clients.

By storing the location information in an LDAP directory, FedFS junctions on multiple file servers can refer to the same copy of location information. This common locations metadata can be updated via a single administrative operation, altering the file name space consistently across all servers. The fedfs(7) man page has more information.

DESCRIPTION

The nfsref(8) command is a simple way to get started managing junction metadata. Other administrative commands provide richer access to junction information.

Subcommands

Valid nfsref(8) subcommands are:

add

Adds junction information to the directory named by pathname. The named directory must already exist, and must not already contain junction information. Regular directory contents are obscured to NFS clients by this operation.

A list of one or more file server and export path pairs is also specified on the command line. When creating an NFS basic junction, this list is stored in an extended attribute of the directory.

When creating a FedFS junction, FedFS records containing the file server and export path pairs are created on an LDAP server, and a pointer to the new FedFS records is stored in an extended attribute of the directory. Fresh FSN and FSL UUIDs are generated during this operation.

If junction creation is successful, the nfsref(8) command flushes the kernel's export cache to remove previously cached junction information.

remove

Removes junction information from the directory named by pathname. The named directory must exist, and must contain junction information. Regular directory contents are made visible to NFS clients again by this operation.

When removing a FedFS junction, the nfsref(8) command also removes FSN and FSL records referred to in the junction.

If junction deletion is successful, the nfsref(8) command flushes the kernel's export cache to remove previously cached junction information.

lookup

Displays junction information stored in the directory named by pathname. The named directory must exist, and must contain junction information.

When looking up an NFS basic junction, the junction information in the directory is listed on stdout. When looking up a FedFS junction, junction information is retrieved from the LDAP server listed in the junction and listed on stdout.

When creating a new FedFS junction, the nfsref(8) command reads the following environment variables:

FEDFS_NSDB_HOST

Specifies the hostname of the LDAP server where new FedFS records should reside. If this variable is not set, the nfsref(8) command fails. The LDAP server specified by this variable must be registered with the local NSDB connection parameter database before the nfsref(8) command can communicate with it. See nsdbparams(8) for more information.

FEDFS_NSDB_PORT

Specifies the IP port of the LDAP server where new FedFS records should reside. The default value if this variable is not set is 389.

FEDFS_NSDB_NCE

Specifies the distinguished name of the NSDB Container Entry under which new FedFS records should reside. If this variable is not set, the local NSDB connection parameter database is searched for a default NCE for the hostname specified by FEDFS_NSDB_HOST. If neither of these is specified, the nfsref(8) command fails.

FEDFS_NSDB_ADMIN

Specifies a distinguished name of an entity used to bind to the LDAP server where new FedFS records should reside. If this variable is not set, the local NSDB connection parameter database is searched for a default bind DN for the hostname specified by FEDFS_NSDB_HOST. If neither of these is specified, or if this entity does not have permission to modify the LDAP server's DIT, the nfsref(8) command fails.

Command line options

-d, --debug

Enables debugging messages during operation.

-t, --type=junction-type

Specifies the junction type for the operation. Valid values for junction-type are nfs-basic or nfs-fedfs.

For the add subcommand, the default value if this option is not specified is nfs-basic. For the remove and lookup subcommands, the --type option is not required. The nfsref(8) command operates on whatever junction contents are available.

EXAMPLES

Suppose you have two file servers, top.example.net and home.example.net. You want all your clients to mount top.example.net:/ and then see the files under home.example.net:/ automatically in top:/home.

On top.example.net, you might issue this command as root:

# mkdir /home
# nfsref --type=nfs-basic add /home home.example.net /
Created junction /home.

FILES

/etc/exports

NFS server export table

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>