1
2NFSREF(8)                   System Manager's Manual                  NFSREF(8)
3
4
5

NAME

7       nfsref - manage NFS referrals
8

SYNOPSIS

10       nfsref [-?d] [-t type] add pathname server export [ server export ... ]
11
12       nfsref [-?d] [-t type] remove pathname
13
14       nfsref [-?d] [-t type] lookup pathname
15

INTRODUCTION

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
24       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
29       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
34       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
39       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
44       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
49       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
53       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

DESCRIPTION

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
64   Subcommands
65       Valid nfsref(8) subcommands are:
66
67       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
72              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
77              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
83              If  junction  creation  is  successful,  the  nfsref(8)  command
84              flushes the kernel's export cache to  remove  previously  cached
85              junction information.
86
87       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
92              When removing a  FedFS  junction,  the  nfsref(8)  command  also
93              removes FSN and FSL records referred to in the junction.
94
95              If  junction  deletion  is  successful,  the  nfsref(8)  command
96              flushes the kernel's export cache to  remove  previously  cached
97              junction information.
98
99       lookup Displays  junction  information stored in the directory named by
100              pathname.  The named directory  must  exist,  and  must  contain
101              junction information.
102
103              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
108       When creating a new FedFS junction, the  nfsref(8)  command  reads  the
109       following environment variables:
110
111       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
119       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
124       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
132       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
141   Command line options
142       -d, --debug
143              Enables debugging messages during operation.
144
145       -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
149              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

EXAMPLES

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
159       On top.example.net, you might issue this command as root:
160
161              # mkdir /home
162              # nfsref --type=nfs-basic add /home home.example.net /
163              Created junction /home.
164
165

FILES

167       /etc/exports
168              NFS server export table
169

SEE ALSO

171       fedfs(7), nsdbparams(8), exports(5)
172
173       RFC 5661 for a description of NFS version 4 referrals
174
175       RFC 5716 for FedFS requirements and overview
176

COLOPHON

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

AUTHOR

183       Chuck Lever <chuck.lever@oracle.com>
184
185
186
187                                3 February 2014                      NFSREF(8)
Impressum