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
19       A file system referral is like a symbolic link (or, symlink) to another
20       file system share, typically on another file server.   An  NFS  client,
21       under  the  server's direction, mounts the referred-to NFS export auto‐
22       matically when an application first accesses it.
23
24       NFSv4 referrals can be used to transparently redirect clients  to  file
25       systems  that  have been moved elsewhere, or to construct a single file
26       name space across multiple file servers.  Because file servers  control
27       the  shape of the whole file name space, no client configuration is re‐
28       quired.
29

DESCRIPTION

31       A junction is a file system object on an NFS server that, when  an  NFS
32       client  encounters  it,  triggers  a referral.  Similar to a symlink, a
33       junction contains one or more target locations that the server sends to
34       clients in the form of an NFSv4 referral.
35
36       On Linux, an existing directory can be converted to a junction and back
37       atomically and without the loss of the directory contents.  When a  di‐
38       rectory  acts  as  a  junction, it's local content is hidden from NFSv4
39       clients.
40
41       The nfsref(8) command is a simple way to get started managing junctions
42       and their content.
43
44   Subcommands
45       Valid nfsref(8) subcommands are:
46
47       add    Adds  junction  information  to the directory named by pathname.
48              The named directory must already exist,  and  must  not  already
49              contain  junction  information.   Regular directory contents are
50              obscured to NFS clients by this operation.
51
52              A list of one or more file server and export path pairs is  also
53              specified on the command line.  When creating an NFS basic junc‐
54              tion, this list is stored in an extended attribute of the direc‐
55              tory.
56
57              If  junction  creation  is  successful,  the  nfsref(8)  command
58              flushes the kernel's export cache to  remove  previously  cached
59              junction information.
60
61       remove Removes  junction  information from the directory named by path‐
62              name.  The named directory must exist, and must contain junction
63              information.  Regular directory contents are made visible to NFS
64              clients again by this operation.
65
66              If  junction  deletion  is  successful,  the  nfsref(8)  command
67              flushes  the  kernel's  export cache to remove previously cached
68              junction information.
69
70       lookup Displays junction information stored in the directory  named  by
71              pathname.   The  named  directory  must  exist, and must contain
72              junction information.
73
74              When looking up an NFS basic junction, the junction  information
75              in the directory is listed on stdout.
76
77   Command line options
78       -d, --debug
79              Enables debugging messages during operation.
80
81       -t, --type=junction-type
82              Specifies the junction type for the operation.  Valid values for
83              junction-type are nfs-basic or nfs-fedfs.
84
85              For the add subcommand, the default value if this option is  not
86              specified  is nfs-basic.  The nfs-fedfs type is not used in this
87              implementation.
88
89              For the remove and lookup subcommands, the --type option is  not
90              required.   The  nfsref(8) command operates on whatever junction
91              contents are available.
92

EXAMPLES

94       Suppose you have  two  file  servers,  top.example.net  and  home.exam‐
95       ple.net.  You want all your clients to mount top.example.net:/ and then
96       see the files under home.example.net:/ automatically in top:/home.
97
98       On top.example.net, you might issue this command as root:
99
100              # mkdir /home
101              # nfsref add /home home.example.net /
102              Created junction /home.
103
104

SEE ALSO

106       RFC 8881 for a description of the NFS version 4 referral mechanism
107

AUTHOR

109       Chuck Lever <chuck.lever@oracle.com>
110
111
112
113                                  9 Jan 2018                         NFSREF(8)
Impressum