Debian Codegraph @

upstream/debian-unstable/man8/nfsref.8

raw
1 .\"@(#)nfsref.8"
2 .\"
3 .\" @file utils/nfsref/nfsref.man
4 .\" @brief man page for nfsref command
5 .\"
6
7 .\"
8 .\" Copyright 2011, 2018 Oracle. All rights reserved.
9 .\"
10 .\" This file is part of nfs-utils.
11 .\"
12 .\" nfs-utils is free software; you can redistribute it and/or modify
13 .\" it under the terms of the GNU General Public License version 2.0 as
14 .\" published by the Free Software Foundation.
15 .\"
16 .\" nfs-utils is distributed in the hope that it will be useful, but
17 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
18 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 .\" GNU General Public License version 2.0 for more details.
20 .\"
21 .\" You should have received a copy of the GNU General Public License
22 .\" version 2.0 along with nfs-utils. If not, see:
23 .\"
24 .\" http://www.gnu.org/licenses/old-licenses/gpl-2.0.txt
25 .\"
26 .TH NFSREF 8 "9 Jan 2018"
27 .SH NAME
28 nfsref \- manage NFS referrals
29 .SH SYNOPSIS
30 .B nfsref
31 .RB [ \-?d ]
32 .RB [ \-t
33 .IB type ]
34 .B add
35 .I pathname server export
36 .RI [ " server"
37 .IR export " ... ]"
38 .P
39 .B nfsref
40 .RB [ \-?d ]
41 .RB [ \-t
42 .IB type ]
43 .B remove
44 .I pathname
45 .P
46 .B nfsref
47 .RB [ \-?d ]
48 .RB [ \-t
49 .IB type ]
50 .B lookup
51 .I pathname
52 .SH INTRODUCTION
53 NFS version 4 introduces the concept of
54 .I file system referrals
55 to NFS.
56 .P
57 A file system referral is like a symbolic link
58 (or,
59 .IR symlink )
60 to another file system share, typically on another file server.
61 An NFS client, under the server's direction,
62 mounts the referred-to NFS export
63 automatically when an application first accesses it.
64 .P
65 NFSv4 referrals can be used to transparently redirect clients
66 to file systems that have been moved elsewhere, or
67 to construct a single file name space across multiple file servers.
68 Because file servers control the shape of the whole file name space,
69 no client configuration is required.
70 .P
71 .SH DESCRIPTION
72 A
73 .I junction
74 is a file system object on an NFS server that,
75 when an NFS client encounters it, triggers a referral.
76 Similar to a symlink, a junction contains one or more target locations
77 that the server sends to clients in the form of an NFSv4 referral.
78 .P
79 On Linux, an existing directory can be converted to a junction
80 and back atomically and without the loss of the directory contents.
81 When a directory acts as a junction, it's local content is hidden
82 from NFSv4 clients.
83 .P
84 The
85 .BR nfsref (8)
86 command is a simple way to get started managing junctions and their content.
87 .SS Subcommands
88 Valid
89 .BR nfsref (8)
90 subcommands are:
91 .IP "\fBadd\fP"
92 Adds junction information to the directory named by
93 .IR pathname .
94 The named directory must already exist,
95 and must not already contain junction information.
96 Regular directory contents are obscured to NFS clients by this operation.
97 .IP
98 A list of one or more file server and export path pairs
99 is also specified on the command line.
100 When creating an NFS basic junction, this list is
101 stored in an extended attribute of the directory.
102 .IP
103 If junction creation is successful, the
104 .BR nfsref (8)
105 command flushes the kernel's export cache
106 to remove previously cached junction information.
107 .IP "\fBremove\fP"
108 Removes junction information from the directory named by
109 .IR pathname .
110 The named directory must exist,
111 and must contain junction information.
112 Regular directory contents are made visible to NFS clients again by this operation.
113 .IP
114 If junction deletion is successful, the
115 .BR nfsref (8)
116 command flushes the kernel's export cache
117 to remove previously cached junction information.
118 .IP "\fBlookup\fP"
119 Displays junction information stored in the directory named by
120 .IR pathname .
121 The named directory must exist,
122 and must contain junction information.
123 .IP
124 When looking up an NFS basic junction, the junction information
125 in the directory is listed on
126 .IR stdout .
127 .SS Command line options
128 .IP "\fB\-d, \-\-debug"
129 Enables debugging messages during operation.
130 .IP "\fB\-t, \-\-type=\fIjunction-type\fP"
131 Specifies the junction type for the operation. Valid values for
132 .I junction-type
133 are
134 .B nfs-basic
135 or
136 .BR nfs-fedfs .
137 .IP
138 For the
139 .B add
140 subcommand, the default value if this option is not specified is
141 .BR nfs-basic .
142 The
143 .B nfs-fedfs
144 type is not used in this implementation.
145 .IP
146 For the
147 .B remove
148 and
149 .B lookup
150 subcommands, the
151 .B \-\-type
152 option is not required. The
153 .BR nfsref (8)
154 command operates on whatever junction contents are available.
155 .SH EXAMPLES
156 Suppose you have two file servers,
157 .I top.example.net
158 and
159 .IR home.example.net .
160 You want all your clients to mount
161 .I top.example.net:/
162 and then see the files under
163 .I home.example.net:/
164 automatically in
165 .IR top:/home .
166 .P
167 On
168 .IR top.example.net ,
169 you might issue this command as root:
170 .RS
171 .sp
172 # mkdir /home
173 .br
174 # nfsref add /home home.example.net /
175 .br
176 Created junction /home.
177 .sp
178 .RE
179 .SH "SEE ALSO"
180 RFC 8881 for a description of the NFS version 4 referral mechanism
181 .SH "AUTHOR"
182 Chuck Lever <[email protected]>