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