1.\" Copyright (c) 1989, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 4. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)exports.5 8.3 (Berkeley) 3/29/95 29.\" $FreeBSD$ 30.\" 31.Dd June 30, 2008 32.Dt EXPORTS 5 33.Os 34.Sh NAME 35.Nm exports 36.Nd define remote mount points for 37.Tn NFS 38mount requests 39.Sh SYNOPSIS 40.Nm 41.Sh DESCRIPTION 42The 43.Nm 44file specifies remote mount points for the 45.Tn NFS 46mount protocol per the 47.Tn NFS 48server specification; see 49.%T "Network File System Protocol Specification" , 50RFC1094, Appendix A and 51.%T "NFS: Network File System Version 3 Specification" , 52Appendix I. 53.Pp 54Each line in the file 55(other than comment lines that begin with a #) 56specifies the mount point(s) and export flags within one local server 57file system for one or more hosts. 58A long line may be split over several lines by ending all but the 59last line with a backslash 60.Pq Ql \e . 61A host may be specified only once for each local file system on the 62server and there may be only one default entry for each server 63file system that applies to all other hosts. 64The latter exports the file system to the 65.Dq world 66and should 67be used only when the file system contains public information. 68.Pp 69In a mount entry, 70the first field(s) specify the directory path(s) within a server file system 71that can be mounted on by the corresponding client(s). 72There are two forms of this specification. 73The first is to list all mount points as absolute 74directory paths separated by whitespace. 75The second is to specify the pathname of the root of the file system 76followed by the 77.Fl alldirs 78flag; 79this form allows the host(s) to mount at any point within the file system, 80including regular files if the 81.Fl r 82option is used on 83.Xr mountd 8 . 84The pathnames must not have any symbolic links in them and should not have 85any 86.Dq Pa \&. 87or 88.Dq Pa .. 89components. 90Mount points for a file system may appear on multiple lines each with 91different sets of hosts and export options. 92.Pp 93The second component of a line specifies how the file system is to be 94exported to the host set. 95The option flags specify whether the file system 96is exported read-only or read-write and how the client UID is mapped to 97user credentials on the server. 98.Pp 99Export options are specified as follows: 100.Pp 101.Sm off 102.Fl maproot Li = Sy user 103.Sm on 104The credential of the specified user is used for remote access by root. 105The credential includes all the groups to which the user is a member 106on the local machine (see 107.Xr id 1 ) . 108The user may be specified by name or number. 109.Pp 110.Sm off 111.Fl maproot Li = Sy user:group1:group2:... 112.Sm on 113The colon separated list is used to specify the precise credential 114to be used for remote access by root. 115The elements of the list may be either names or numbers. 116Note that user: should be used to distinguish a credential containing 117no groups from a complete credential for that user. 118.Pp 119.Sm off 120.Fl mapall Li = Sy user 121.Sm on 122or 123.Sm off 124.Fl mapall Li = Sy user:group1:group2:... 125.Sm on 126specifies a mapping for all client UIDs (including root) 127using the same semantics as 128.Fl maproot . 129.Pp 130The option 131.Fl r 132is a synonym for 133.Fl maproot 134in an effort to be backward compatible with older export file formats. 135.Pp 136In the absence of 137.Fl maproot 138and 139.Fl mapall 140options, remote accesses by root will result in using a credential of -2:-2. 141All other users will be mapped to their remote credential. 142If a 143.Fl maproot 144option is given, 145remote access by root will be mapped to that credential instead of -2:-2. 146If a 147.Fl mapall 148option is given, 149all users (including root) will be mapped to that credential in 150place of their own. 151.Pp 152The 153.Fl ro 154option specifies that the file system should be exported read-only 155(default read/write). 156The option 157.Fl o 158is a synonym for 159.Fl ro 160in an effort to be backward compatible with older export file formats. 161.Pp 162.Tn WebNFS 163exports strictly according to the spec (RFC 2054 and RFC 2055) can 164be done with the 165.Fl public 166flag. 167However, this flag in itself allows r/w access to all files in 168the file system, not requiring reserved ports and not remapping UIDs. 169It 170is only provided to conform to the spec, and should normally not be used. 171For a 172.Tn WebNFS 173export, 174use the 175.Fl webnfs 176flag, which implies 177.Fl public , 178.Sm off 179.Fl mapall No = Sy nobody 180.Sm on 181and 182.Fl ro . 183Note that only one file system can be 184.Tn WebNFS 185exported on a server. 186.Pp 187A 188.Sm off 189.Fl index No = Pa file 190.Sm on 191option can be used to specify a file whose handle will be returned if 192a directory is looked up using the public filehandle 193.Pq Tn WebNFS . 194This is to mimic the behavior of URLs. 195If no 196.Fl index 197option is specified, a directory filehandle will be returned as usual. 198The 199.Fl index 200option only makes sense in combination with the 201.Fl public 202or 203.Fl webnfs 204flags. 205.Pp 206Specifying the 207.Fl quiet 208option will inhibit some of the syslog diagnostics for bad lines in 209.Pa /etc/exports . 210This can be useful to avoid annoying error messages for known possible 211problems (see 212.Sx EXAMPLES 213below). 214.Pp 215The third component of a line specifies the host set to which the line applies. 216The set may be specified in three ways. 217The first way is to list the host name(s) separated by white space. 218(Standard Internet 219.Dq dot 220addresses may be used in place of names.) 221The second way is to specify a 222.Dq netgroup 223as defined in the 224.Pa netgroup 225file (see 226.Xr netgroup 5 ) . 227The third way is to specify an Internet subnetwork using a network and 228network mask that is defined as the set of all hosts with addresses within 229the subnetwork. 230This latter approach requires less overhead within the 231kernel and is recommended for cases where the export line refers to a 232large number of clients within an administrative subnet. 233.Pp 234The first two cases are specified by simply listing the name(s) separated 235by whitespace. 236All names are checked to see if they are 237.Dq netgroup 238names 239first and are assumed to be hostnames otherwise. 240Using the full domain specification for a hostname can normally 241circumvent the problem of a host that has the same name as a netgroup. 242The third case is specified by the flag 243.Sm off 244.Fl network Li = Sy netname Op Li / Ar prefixlength 245.Sm on 246and optionally 247.Sm off 248.Fl mask No = Sy netmask . 249.Sm on 250The netmask may be specified either by attaching a 251.Ar prefixlength 252to the 253.Fl network 254option, or by using a separate 255.Fl mask 256option. 257If the mask is not specified, it will default to the mask for that network 258class (A, B or C; see 259.Xr inet 4 ) . 260See the 261.Sx EXAMPLES 262section below. 263.Pp 264Scoped IPv6 address must carry scope identifier as documented in 265.Xr inet6 4 . 266For example, 267.Dq Li fe80::%re2/10 268is used to specify 269.Li fe80::/10 270on 271.Li re2 272interface. 273.Pp 274The 275.Xr mountd 8 276utility can be made to re-read the 277.Nm 278file by sending it a hangup signal as follows: 279.Bd -literal -offset indent 280/etc/rc.d/mountd reload 281.Ed 282.Pp 283After sending the 284.Dv SIGHUP , 285check the 286.Xr syslogd 8 287output to see whether 288.Xr mountd 8 289logged any parsing errors in the 290.Nm 291file. 292.Sh FILES 293.Bl -tag -width /etc/exports -compact 294.It Pa /etc/exports 295the default remote mount-point file 296.El 297.Sh EXAMPLES 298.Bd -literal -offset indent 299/usr /usr/local -maproot=0:10 friends 300/usr -maproot=daemon grumpy.cis.uoguelph.ca 131.104.48.16 301/usr -ro -mapall=nobody 302/u -maproot=bin: -network 131.104.48 -mask 255.255.255.0 303/a -network 192.168.0/24 304/a -network 3ffe:1ce1:1:fe80::/64 305/u2 -maproot=root friends 306/u2 -alldirs -network cis-net -mask cis-mask 307/cdrom -alldirs,quiet,ro -network 192.168.33.0 -mask 255.255.255.0 308.Ed 309.Pp 310Given that 311.Pa /usr , /u , /a 312and 313.Pa /u2 314are 315local file system mount points, the above example specifies the following: 316.Pp 317The file system rooted at 318.Pa /usr 319is exported to hosts 320.Em friends 321where friends is specified in the netgroup file 322with users mapped to their remote credentials and 323root mapped to UID 0 and group 10. 324It is exported read-write and the hosts in 325.Dq friends 326can mount either 327.Pa /usr 328or 329.Pa /usr/local . 330It is exported to 331.Em 131.104.48.16 332and 333.Em grumpy.cis.uoguelph.ca 334with users mapped to their remote credentials and 335root mapped to the user and groups associated with 336.Dq daemon ; 337it is exported to the rest of the world as read-only with 338all users mapped to the user and groups associated with 339.Dq nobody . 340.Pp 341The file system rooted at 342.Pa /u 343is exported to all hosts on the subnetwork 344.Em 131.104.48 345with root mapped to the UID for 346.Dq bin 347and with no group access. 348.Pp 349The file system rooted at 350.Pa /u2 351is exported to the hosts in 352.Dq friends 353with root mapped to UID and groups 354associated with 355.Dq root ; 356it is exported to all hosts on network 357.Dq cis-net 358allowing mounts at any 359directory within /u2. 360.Pp 361The file system rooted at 362.Pa /a 363is exported to the network 192.168.0.0, with a netmask of 255.255.255.0. 364However, the netmask length in the entry for 365.Pa /a 366is not specified through a 367.Fl mask 368option, but through the 369.Li / Ns Ar prefix 370notation. 371.Pp 372The file system rooted at 373.Pa /a 374is also exported to the IPv6 network 375.Li 3ffe:1ce1:1:fe80:: 376address, using the upper 64 bits as the prefix. 377Note that, unlike with IPv4 network addresses, the specified network 378address must be complete, and not just contain the upper bits. 379With IPv6 addresses, the 380.Fl mask 381option must not be used. 382.Pp 383The file system rooted at 384.Pa /cdrom 385will be exported read-only to the entire network 192.168.33.0/24, including 386all its subdirectories. 387Since 388.Pa /cdrom 389is the conventional mountpoint for a CD-ROM device, this export will 390fail if no CD-ROM medium is currently mounted there since that line 391would then attempt to export a subdirectory of the root file system 392with the 393.Fl alldirs 394option which is not allowed. 395The 396.Fl quiet 397option will then suppress the error message for this condition that 398would normally be syslogged. 399As soon as an actual CD-ROM is going to be mounted, 400.Xr mount 8 401will notify 402.Xr mountd 8 403about this situation, and the 404.Pa /cdrom 405file system will be exported as intended. 406Note that without using the 407.Fl alldirs 408option, the export would always succeed. 409While there is no CD-ROM medium mounted under 410.Pa /cdrom , 411it would export the (normally empty) directory 412.Pa /cdrom 413of the root file system instead. 414.Sh SEE ALSO 415.Xr netgroup 5 , 416.Xr mountd 8 , 417.Xr nfsd 8 , 418.Xr showmount 8 419.Sh BUGS 420The export options are tied to the local mount points in the kernel and 421must be non-contradictory for any exported subdirectory of the local 422server mount point. 423It is recommended that all exported directories within the same server 424file system be specified on adjacent lines going down the tree. 425You cannot specify a hostname that is also the name of a netgroup. 426Specifying the full domain specification for a hostname can normally 427circumvent the problem. 428