FedFsNfsRefGuide0.9

From Linux NFS

Contents 1 Project: fedfs-utils 2 Introduction 3 The nfsref command 3.1 Adding a junction 3.2 Viewing a junction's locations 3.3 Removing a junction 4 Junctions in a domain root directory 5 Junction types 6 FedFS junctions 6.1 Set up an LDAP server and turn it into an NSDB 6.2 Use the nsdbparams command to tell the fileserver how to contact the NSDB 6.3 Set up environment variables 6.4 Create your FedFS junctions

Project: fedfs-utils

[ Project Home | News | Downloads | Docs | Mailing Lists | Source Control | Issues ]

---

Introduction

A FedFS domain namespace is composed of individual shared filesystems that are joined together by junctions. A junction is a physical object stored on a fileserver that triggers a "referral" when a file-access client attempts to access it. A referral contains information that such a client uses to find and mount the referred-to fileserver.

This article describes how to set up junctions on Linux NFS servers.

The nfsref command

On Linux, the nfsref command creates and removes junctions recognized by the NFS server. The arguments are the local pathname of the junction, and a list of NFS server and export pathname pairs. We call these pairs "fileset locations," or simply "locations" for short.

Adding a junction

Suppose you'd like to create a junction called "junction" in a fileserver's /export directory that refers clients to the export /foo/bar on the NFS server server.example.net. The nfsref command to do this looks like this:

# nfsref add /export/junction server.example.net /foo/bar

Now, when an NFS client mounts /export and tries to "cd" into /export/junction, it will mount server.example.net:/foo/bar and cd into it.

You can list more than one location when creating a junction. Clients will each choose to mount one of these locations. This makes sense only if all the listed locations have precisely the same data.

A junction can be created on any export on a fileserver, in any directory. In this way, a hierarchy of filesystems can be defined, linked together by junctions.

Viewing a junction's locations

On the server, it's easy to see what locations are contained in /export/junction:

# nfsref lookup /export/junction

Removing a junction

When you no longer want the junction, use:

# nfsref remove /export/junction

In order to alter location information stored in a junction, the junction must be removed and created again.

Junctions in a domain root directory

A FedFS domain's top-level directory is known as its domain root directory. This directory typically contains nothing but junctions that point to other, more interesting fileservers with real data.

Let's assume you've already set up a domain root export and domain root directory, say on server.example.net. On this fileserver, cd into the domain root directory, and create some junctions.

# cd /.domainroot/example.net
# nfsref add sales sales.example.net /
# nfsref add marketing marketing.example.net /public
# nfsref add engineering engr.example.net /source

Now, when a shell user on a FedFS-enabled NFS client changes to /nfs4/example.net, she will see these directories:

sales marketing engineering

Changing into any of these directories will take her directly to the location listed in that junction.

Junction types

In the above examples, we created "NFS basic" junctions. That simply means that locations are stored right in the junction itself on the fileserver. This is the default type of junction created by the nfsref command.

However, the nfsref command can also create "FedFS" junctions. In this type of junction, locations are stored remotely on an LDAP server. This becomes interesting when junctions on several fileservers refer to the same location.

In other words, suppose you have four fileservers: A, B, C, and D. Suppose further that D has an interesting export called /x/y/z. You'd like to create junctions on A, B, and C that refer to D:/x/y/z. If you store that location information on a remote LDAP server, then you can change the location these junctions refer to simply by updating the location information on that LDAP server. In fact, you don't even need to know how many junctions use that location information: they will all be updated automatically when you update the location on the LDAP server.

A FedFS junction simply refers the fileserver to an entry on the LDAP server which contains the relevant location information for that junction. In the next section, we'll describe how to manage FedFS junctions using the nfsref command.

FedFS junctions

In order to enable automatic resolution of a FedFS junction (that is, to allow fileservers to find the LDAP server with the right location information), some set up is needed first.

Set up an LDAP server and turn it into an NSDB

Find instructions and recipes on how to do this elsewhere in the Installation Guide.

Use the nsdbparams command to tell the fileserver how to contact the NSDB

The NSDB may require some transport layer security. Suppose your NSDB was at nsdb.example.net. On your fileservers, start with this command:

# nsdbparams update nsdb.example.net

If nsdb.example.net requires TLS, you can use the nsdbparams command to add a certificate that the fileserver will use every time it needs to contact the NSDB. You will need to do this for all NSDBs the fileserver is allowed to contact, including NSDBs not in your FedFS domain.

Set up environment variables

The environmental variables FEDFS_NSDB_HOST, FEDFS_NSDB_PORT, FEDFS_NSDB_ADMIN, and FEDFS_NSDB_NCE specify what NSDB to use when creating junctions in your FedFS domain. For convenience, the nfsref command uses the values contained in these variables rather than requiring extra command line options. You'll get these when you set up your NSDB.

# export FEDFS_NSDB_HOST="nsdb.example.net"
# export FEDFS_NSDB_ADMIN="cn=Directory Manager"
# export FEDFS_NSDB_NCE="ou=fedfs,dc=example,dc=net"

Create your FedFS junctions

This works just like creating an NFS basic junction, except that you specify "-t nfs-fedfs" on the "nfsref add" command. After setting up the NSDB and environment variables:

# nfsref -t nfs-fedfs add /.domainroot/example.net/sales sales.example.net /

When an NFS client cd's into /nfs4/example.net/sales, it will mount sales.example.net:/ and cd into it. The NFS server will automatically find the location sales.example.net:/ by contacting the NSDB nsdb.example.net and querying it for the location.

In theory, FedFS junctions can share the same location information. However, the nfsref command always creates a unique set of entries on an NSDB for each junction. It does not allow location sharing. In the future, new administrative interfaces will be developed that can share location information between junctions.