| blob | 5d3d809373062bbfa406100110654f01fe46d0ce |
1 .\" $NetBSD: exports.5,v 1.29 2006/10/08 16:35:19 apb Exp $
2 .\"
3 .\" Copyright (c) 1989, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)exports.5 8.3 (Berkeley) 3/29/95
31 .\"
32 .Dd October 8, 2006
33 .Dt EXPORTS 5
34 .Os
35 .Sh NAME
36 .Nm exports
37 .Nd define remote mount points for
38 .Tn NFS
39 mount requests
40 .Sh SYNOPSIS
41 .Nm exports
42 .Sh DESCRIPTION
43 The
44 .Nm exports
45 file specifies remote mount points for the
46 .Tn NFS
47 mount protocol per the
48 .Tn NFS
49 server specification; see
50 .%T "Network File System Protocol Specification \\*(tNRFC\\*(sP 1094, Appendix A"
51 and
52 .%T "NFS: Network File System Version 3 Specification, Appendix I" .
53 .Pp
54 Each line in the file
55 (other than comment lines that begin with a
56 .Sq # )
57 specifies the mount point(s) and export flags within one local server
58 filesystem for one or more hosts.
59 A host may be specified only once for each local filesystem on the
60 server and there may be only one default entry for each server
61 filesystem that applies to all other hosts.
62 The latter exports the filesystem to the
63 .Dq world
64 and should
65 be used only when the filesystem contains public information.
66 .Pp
67 If you have modified the
68 .Pa /etc/exports
69 file, send the mountd a SIGHUP to make it re-read the
70 .Pa /etc/exports
71 file:
72 .Dq kill -HUP `cat /var/run/mountd.pid` .
73 .Pp
74 In a mount entry,
75 the first field(s) specify the directory path(s) within a server filesystem
76 that can be mounted on by the corresponding client(s).
77 There are two forms of this specification.
78 The first is to list all mount points as absolute
79 directory paths separated by whitespace.
80 The second is to specify the pathname of the root of the filesystem
81 followed by the
82 .Fl alldirs
83 flag;
84 this form allows the host(s) to mount at any point within the filesystem,
85 including regular files.
86 Note that the
87 .Fl alldirs
88 option should not be used as a security measure to make clients mount
89 only those subdirectories that they should have access to.
90 A client
91 can still access the whole filesystem via individual RPCs if it
92 wanted to, even if just one subdirectory has been mounted.
93 The pathnames must not have any symbolic links in them and should not have
94 any
95 .Dq .
96 or
97 .Dq ..
98 components.
99 Mount points for a filesystem may appear on multiple lines each with
100 different sets of hosts and export options.
101 .Pp
102 The second component of a line specifies how the filesystem is to be
103 exported to the host set.
104 The option flags specify whether the filesystem
105 is exported read-only or read-write and how the client uid is mapped to
106 user credentials on the server.
107 .Pp
108 Export options are specified as follows:
109 .Pp
110 .Sm off
111 .Fl maproot No = Ar user
112 .Sm on
113 The credential of the specified user is used for remote access by root.
114 The credential includes all the groups to which the user is a member
115 on the local machine (see
116 .Xr id 1 ) .
117 The user may be specified by name or number.
118 .Pp
119 .Sm off
120 .Fl maproot No = Ar user : group1 : group2 : ...
121 .Sm on
122 The colon separated list is used to specify the precise credential
123 to be used for remote access by root.
124 The elements of the list may be either names or numbers.
125 Note that user: should be used to distinguish a credential containing
126 no groups from a complete credential for that user.
127 .Pp
128 .Sm off
129 .Fl mapall No = Ar user
130 .Sm on
131 or
132 .Sm off
133 .Fl mapall No = Ar user : group1 : group2 : ...
134 .Sm on
135 specifies a mapping for all client uids (including root)
136 using the same semantics as
137 .Fl maproot .
138 .Pp
139 The option
140 .Fl r
141 is a synonym for
142 .Fl maproot
143 in an effort to be backward compatible with older export file formats.
144 .Pp
145 In the absence of
146 .Fl maproot
147 and
148 .Fl mapall
149 options, remote accesses by root will result in using a credential of -2:-2.
150 All other users will be mapped to their remote credential.
151 If a
152 .Fl maproot
153 option is given,
154 remote access by root will be mapped to that credential instead of -2:-2.
155 If a
156 .Fl mapall
157 option is given,
158 all users (including root) will be mapped to that credential in
159 place of their own.
160 .Pp
161 The
162 .Fl kerb
163 option specifies that the Kerberos authentication server should be
164 used to authenticate and map client credentials.
165 This option is currently not implemented.
166 .Pp
167 The
168 .Fl ro
169 option specifies that the filesystem should be exported read-only
170 (default read/write).
171 The option
172 .Fl o
173 is a synonym for
174 .Fl ro
175 in an effort to be backward compatible with older export file formats.
176 .Pp
177 The
178 .Fl noresvport
179 option specifies that NFS RPC calls for the filesystem do not have to come
180 from reserved ports.
181 Normally, clients are required to use reserved ports for operations.
182 Using this option decreases the security of your system.
183 .Pp
184 The
185 .Fl noresvmnt
186 option specifies that mount RPC requests for the filesystem do not have
187 to come from reserved ports.
188 Normally, clients are required to use reserved ports for mount requests.
189 Using this option decreases the security of your system.
190 .Pp
191 WebNFS exports strictly according to the spec (RFC 2054 and RFC 2055) can
192 be done with the
193 .Fl public
194 flag.
195 However, this flag in itself allows r/w access to all files in
196 the filesystem, not requiring reserved ports and not remapping uids.
197 It is only provided to conform to the spec, and should normally
198 not be used.
199 For a WebNFS export,
200 use the
201 .Fl webnfs
202 flag, which implies
203 .Fl public ,
204 .Sm off
205 .Fl mapall No = Ar nobody
206 .Sm on
207 and
208 .Fl ro .
209 .Pp
210 A
211 .Sm off
212 .Fl index No = Ar file
213 .Sm on
214 option can be used to specify a file whose handle will be returned if
215 a directory is looked up using the public filehandle (WebNFS).
216 This is to mimic the behavior of URLs.
217 If no
218 .Fl index
219 option is specified, a directory filehandle will be returned as usual.
220 The
221 .Fl index
222 option only makes sense in combination with the
223 .Fl public
224 or
225 .Fl webnfs
226 flags.
227 .Pp
228 .Bf -symbolic
229 Warning: exporting a filesystem both using WebNFS and read/write in
230 the normal way to other hosts should be avoided in an environment
231 that is vulnerable to IP spoofing.
232 .Ef
233 WebNFS enables any client to get filehandles to the exported filesystem.
234 Using IP spoofing, a client could then pretend to be a host to which
235 the same filesystem was exported read/write, and use the handle to
236 gain access to that filesystem.
237 .Pp
238 The third component of a line specifies the host set to which the line applies.
239 If no host set is specified, the filesystem is exported to everyone.
240 The set may be specified in three ways.
241 The first way is to list the host name(s) separated by white space.
242 (Standard internet
243 .Dq dot
244 addresses may be used in place of names.)
245 The second way is to specify a
246 .Dq netgroup
247 as defined in the netgroup file (see
248 .Xr netgroup 5 ) .
249 A netgroup that contains an item that does have a host entry
250 is treated like an error.
251 The third way is to specify an internet subnetwork using a network and
252 network mask that is defined as the set of all hosts with addresses within
253 the subnetwork.
254 This latter approach requires less overhead within the
255 kernel and is recommended for cases where the export line refers to a
256 large number of clients within an administrative subnet.
257 .Pp
258 The first two cases are specified by simply listing the name(s) separated
259 by whitespace.
260 All names are checked to see if they are
261 .Dq netgroup
262 names first and are assumed to be hostnames otherwise.
263 Using the full domain specification for a hostname can normally
264 circumvent the problem of a host that has the same name as a netgroup.
265 The third case is specified by the flag
266 .Sm off
267 .Fl network No = Ar netname Op No / Ar prefixlength
268 .Sm on
269 and optionally
270 .Sm off
271 .Fl mask No = Ar netmask .
272 .Sm on
273 The netmask may be specified either by attaching a
274 .Ar prefixlength
275 to the
276 .Fl network
277 option, or by using a separate
278 .Fl mask
279 option.
280 If the mask is not specified, it will default to the mask for that network
281 class (A, B or C; see
282 .Xr inet 4 ) .
283 .Pp
284 Scoped IPv6 address must carry scope identifier as documented in
285 .Xr inet6 4 .
286 For example,
287 .Dq fe80::%ne2/10
288 is used to specify fe80::/10 on ne2 interface.
289 .Pp
290 For example:
291 .Bd -literal -offset indent
292 /usr /usr/local -maproot=0:10 friends
293 /usr -maproot=daemon grumpy.cis.uoguelph.ca 131.104.48.16
294 /usr -ro -mapall=nobody
295 /u -maproot=bin: -network 131.104.48 -mask 255.255.255.0
296 /a -network 192.168.0/24
297 /a -network 3ffe:1ce1:1:fe80::/64
298 /u2 -maproot=root friends
299 /u2 -alldirs -kerb -network cis-net -mask cis-mask
300 .Ed
301 .Pp
302 Given that
303 .Pa /usr ,
304 .Pa /u ,
305 and
306 .Pa /u2
307 are local filesystem mount points, the above example specifies the
308 following:
309 .Pa /usr
310 is exported to hosts
311 .Em friends
312 where friends is specified in the netgroup file
313 with users mapped to their remote credentials and
314 root mapped to uid 0 and group 10.
315 It is exported read-write and the hosts in
316 .Dq friends
317 can mount either
318 .Pa /usr
319 or
320 .Pa /usr/local .
321 It is exported to
322 .Em 131.104.48.16
323 and
324 .Em grumpy.cis.uoguelph.ca
325 with users mapped to their remote credentials and
326 root mapped to the user and groups associated with
327 .Dq daemon ;
328 it is exported to the rest of the world as read-only with
329 all users mapped to the user and groups associated with
330 .Dq nobody .
331 .Pp
332 .Pa /u
333 is exported to all hosts on the subnetwork
334 .Em 131.104.48
335 with root mapped to the uid for
336 .Dq bin
337 and with no group access.
338 .Pp
339 .Pa /u2
340 is exported to the hosts in
341 .Dq friends
342 with root mapped to uid and groups associated with
343 .Dq root ;
344 it is exported to all hosts on network
345 .Dq cis-net
346 allowing mounts at any
347 directory within /u2 and mapping all uids to credentials for the principal
348 that is authenticated by a Kerberos ticket.
349 .Pp
350 .Pa /a
351 is exported to the network 192.168.0.0, with a netmask of 255.255.255.0.
352 However, the netmask length in the entry for /a is not specified through
353 a -mask option, but through the /prefix notation.
354 .Pp
355 .Pa /a
356 is also exported to the IPv6 network 3ffe:1ce1:1:fe80:: address, using
357 the upper 64 bits as the prefix.
358 Note that, unlike with IPv4 network addresses, the specified network
359 address must be complete, and not just contain the upper bits.
360 With IPv6 addresses, the -mask option must not
361 be used.
362 .Sh FILES
363 .Bl -tag -width /etc/exports -compact
364 .It Pa /etc/exports
365 The default remote mount-point file.
366 .El
367 .Sh SEE ALSO
368 .Xr netgroup 5 ,
369 .Xr mountd 8 ,
370 .Xr nfsd 8 ,
371 .Xr showmount 8
372 .Sh CAVEATS
373 Don't re-export NFS-mounted filesystems unless you are sure of the
374 implications.
375 NFS has some assumptions about the characteristics of the file
376 systems being exported, e.g. when timestamps are updated.
377 Re-exporting should work to some extent and can even be useful in
378 some cases, but don't expect it works as well as with local file
379 systems.
380 .Sh BUGS
381 The export options are tied to the local mount points in the kernel and
382 must be non-contradictory for any exported subdirectory of the local
383 server mount point.
384 It is recommended that all exported directories within the same server
385 filesystem be specified on adjacent lines going down the tree.
386 You cannot specify a hostname that is also the name of a netgroup.
387 Specifying the full domain specification for a hostname can normally
388 circumvent the problem.