1NFSREF(8) System Manager's Manual NFSREF(8)
3
7 nfsref - manage NFS referrals
8
10 nfsref [-?d] [-t type] add pathname server export [ server export ... ]
11 nfsref [-?d] [-t type] remove pathname
13 nfsref [-?d] [-t type] lookup pathname
15
17 NFS version 4 introduces the concept of file system referrals to NFS.
18 A file system referral is like a symbolic link on a file server to
19 another file system share, possibly on another file server. On an NFS
20 client, a referral behaves like an automounted directory. The client,
21 under the server's direction, mounts a new NFS export automatically
22 when an application first accesses that directory.
23 Referrals are typically used to construct a single file name space
25 across multiple file servers. Because file servers control the shape
26 of the name space, no client configuration is required, and all clients
27 see the same referral information.
28 The Linux NFS server supports NFS version 4 referrals. Administrators
30 can specify the refer= export option in /etc/exports to configure a
31 list of exports from which the client can choose. See exports(5) for
32 details.
33 The nfsref(8) command provides an alternate way to configure NFS refer‐
35 rals. This command stores referral information as metadata within a
36 leaf directory in an exported file system. The metadata it stores can
37 contain one of two types of information:
38 A list of Fileset Locations
40 A set of server name and export path pairs which are returned
41 verbatim to clients during an NFS referral event. This is known
42 as an NFS basic junction.
43 A Fileset Name
45 The name of an LDAP record which contains information to return
46 to clients during an NFS referral event. This is known as a
47 FedFS junction.
48 A directory can hold either an NFS basic junction or a FedFS junction,
50 but not both. When a directory acts as a junction, its regular con‐
51 tents remain, but are no longer visible to NFS clients.
52 By storing the location information in an LDAP directory, FedFS junc‐
54 tions on multiple file servers can refer to the same copy of location
55 information. This common locations metadata can be updated via a sin‐
56 gle administrative operation, altering the file name space consistently
57 across all servers. The fedfs(7) man page has more information.
58
60 The nfsref(8) command is a simple way to get started managing junction
61 metadata. Other administrative commands provide richer access to junc‐
62 tion information.
63 Subcommands
65 Valid nfsref(8) subcommands are:
66 add Adds junction information to the directory named by pathname.
68 The named directory must already exist, and must not already
69 contain junction information. Regular directory contents are
70 obscured to NFS clients by this operation.
71 A list of one or more file server and export path pairs is also
73 specified on the command line. When creating an NFS basic junc‐
74 tion, this list is stored in an extended attribute of the direc‐
75 tory.
76 When creating a FedFS junction, FedFS records containing the
78 file server and export path pairs are created on an LDAP server,
79 and a pointer to the new FedFS records is stored in an extended
80 attribute of the directory. Fresh FSN and FSL UUIDs are gener‐
81 ated during this operation.
82 If junction creation is successful, the nfsref(8) command
84 flushes the kernel's export cache to remove previously cached
85 junction information.
86 remove Removes junction information from the directory named by path‐
88 name. The named directory must exist, and must contain junction
89 information. Regular directory contents are made visible to NFS
90 clients again by this operation.
91 When removing a FedFS junction, the nfsref(8) command also
93 removes FSN and FSL records referred to in the junction.
94 If junction deletion is successful, the nfsref(8) command
96 flushes the kernel's export cache to remove previously cached
97 junction information.
98 lookup Displays junction information stored in the directory named by
100 pathname. The named directory must exist, and must contain
101 junction information.
102 When looking up an NFS basic junction, the junction information
104 in the directory is listed on stdout. When looking up a FedFS
105 junction, junction information is retrieved from the LDAP server
106 listed in the junction and listed on stdout.
107 When creating a new FedFS junction, the nfsref(8) command reads the
109 following environment variables:
110 FEDFS_NSDB_HOST
112 Specifies the hostname of the LDAP server where new FedFS
113 records should reside. If this variable is not set, the nfs‐
114 ref(8) command fails. The LDAP server specified by this vari‐
115 able must be registered with the local NSDB connection parameter
116 database before the nfsref(8) command can communicate with it.
117 See nsdbparams(8) for more information.
118 FEDFS_NSDB_PORT
120 Specifies the IP port of the LDAP server where new FedFS records
121 should reside. The default value if this variable is not set is
122 389.
123 FEDFS_NSDB_NCE
125 Specifies the distinguished name of the NSDB Container Entry
126 under which new FedFS records should reside. If this variable
127 is not set, the local NSDB connection parameter database is
128 searched for a default NCE for the hostname specified by
129 FEDFS_NSDB_HOST. If neither of these is specified, the nfs‐
130 ref(8) command fails.
131 FEDFS_NSDB_ADMIN
133 Specifies a distinguished name of an entity used to bind to the
134 LDAP server where new FedFS records should reside. If this
135 variable is not set, the local NSDB connection parameter data‐
136 base is searched for a default bind DN for the hostname speci‐
137 fied by FEDFS_NSDB_HOST. If neither of these is specified, or
138 if this entity does not have permission to modify the LDAP
139 server's DIT, the nfsref(8) command fails.
140 Command line options
142 -d, --debug
143 Enables debugging messages during operation.
144 -t, --type=junction-type
146 Specifies the junction type for the operation. Valid values for
147 junction-type are nfs-basic or nfs-fedfs.
148 For the add subcommand, the default value if this option is not
150 specified is nfs-basic. For the remove and lookup subcommands,
151 the --type option is not required. The nfsref(8) command oper‐
152 ates on whatever junction contents are available.
153
155 Suppose you have two file servers, top.example.net and home.exam‐
156 ple.net. You want all your clients to mount top.example.net:/ and then
157 see the files under home.example.net:/ automatically in top:/home.
158 On top.example.net, you might issue this command as root:
160 # mkdir /home
162 # nfsref --type=nfs-basic add /home home.example.net /
163 Created junction /home.
164
167 /etc/exports
168 NFS server export table
169
171 fedfs(7), nsdbparams(8), exports(5)
172 RFC 5661 for a description of NFS version 4 referrals
174 RFC 5716 for FedFS requirements and overview
176
178 This page is part of the fedfs-utils package. A description of the
179 project and information about reporting bugs can be found at
180 http://wiki.linux-nfs.org/wiki/index.php/FedFsUtilsProject.
181
183 Chuck Lever <chuck.lever@oracle.com>
184 3 February 2014 NFSREF(8)