| 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]> |