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.\" 3. 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: src/sbin/mountd/exports.5,v 1.10.2.8 2002/09/28 16:31:45 markm Exp $ 30.\" 31.Dd March 14, 2018 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" , 50RFC 1094, 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 57filesystem for one or more hosts. 58A host may be specified only once for each local filesystem on the 59server and there may be only one default entry for each server 60filesystem that applies to all other hosts. 61The latter exports the filesystem to the 62.Dq world 63and should be used only when the filesystem contains public information. 64.Pp 65In a mount entry, 66the first field(s) specify the directory path(s) within a server filesystem 67that can be mounted on by the corresponding client(s). 68There are two forms of this specification. 69The first is to list all mount points as absolute 70directory paths separated by whitespace. 71This list of directory paths should be considered an 72.Dq administrative control , 73since it is only enforced by the 74.Xr mountd 8 75daemon and not the kernel. 76As such, it only applies to NFSv2 and NFSv3 mounts and only 77with respect to the client's use of the mount protocol. 78The second is to specify the pathname of the root of the filesystem 79followed by the 80.Fl alldirs 81flag; 82this form allows the host(s) to mount at any point within the filesystem, 83including regular files if the 84.Fl r 85option is used on 86.Xr mountd 8 . 87The pathnames must not have any symbolic links in them and should not have 88any 89.Dq Pa \&. 90or 91.Dq Pa .. 92components. 93Mount points for a filesystem may appear on multiple lines each with 94different sets of hosts and export options. 95.Pp 96The second component of a line specifies how the filesystem is to be 97exported to the host set. 98The option flags specify whether the filesystem 99is exported read-only or read-write and how the client UID is mapped to 100user credentials on the server. 101.Pp 102Export options are specified as follows: 103.Pp 104.Sm off 105.Fl maproot Li = Sy user 106.Sm on 107The credential of the specified user is used for remote access by root. 108The credential includes all the groups to which the user is a member 109on the local machine (see 110.Xr id 1 ) . 111The user may be specified by name or number. 112.Pp 113.Sm off 114.Fl maproot Li = Sy user:group1:group2:... 115.Sm on 116The colon separated list is used to specify the precise credential 117to be used for remote access by root. 118The elements of the list may be either names or numbers. 119Note that user: should be used to distinguish a credential containing 120no groups from a complete credential for that user. 121.Pp 122.Sm off 123.Fl mapall Li = Sy user 124.Sm on 125or 126.Sm off 127.Fl mapall Li = Sy user:group1:group2:... 128.Sm on 129specifies a mapping for all client UIDs (including root) 130using the same semantics as 131.Fl maproot . 132.Pp 133The option 134.Fl r 135is a synonym for 136.Fl maproot 137in an effort to be backward compatible with older export file formats. 138.Pp 139In the absence of 140.Fl maproot 141and 142.Fl mapall 143options, remote accesses by root will result in using a credential of 65534:65533. 144All other users will be mapped to their remote credential. 145If a 146.Fl maproot 147option is given, 148remote access by root will be mapped to that credential instead of 65534:65533. 149If a 150.Fl mapall 151option is given, 152all users (including root) will be mapped to that credential in 153place of their own. 154.Pp 155The 156.Fl ro 157option specifies that the filesystem should be exported read-only 158(default read/write). 159The option 160.Fl o 161is a synonym for 162.Fl ro 163in an effort to be backward compatible with older export file formats. 164.Pp 165.Tn WebNFS 166exports strictly according to the spec (RFC 2054 and RFC 2055) can 167be done with the 168.Fl public 169flag. 170However, this flag in itself allows r/w access to all files in 171the file system, not requiring reserved ports and not remapping UIDs. 172It 173is only provided to conform to the spec, and should normally not be used. 174For a 175.Tn WebNFS 176export, 177use the 178.Fl webnfs 179flag, which implies 180.Fl public , 181.Sm off 182.Fl mapall No = Sy nobody 183.Sm on 184and 185.Fl ro . 186.Pp 187A 188.Sm off 189.Fl index No = Sy 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 first and are assumed to be hostnames otherwise. 239Using the full domain specification for a hostname can normally 240circumvent the problem of a host that has the same name as a netgroup. 241The third case is specified by the flag 242.Sm off 243.Fl network Li = Sy netname Op Li / Ar prefixlength 244.Sm on 245and optionally 246.Sm off 247.Fl mask No = Sy netmask . 248.Sm on 249The netmask may be specified either by attaching a 250.Ar prefixlength 251to the 252.Fl network 253option, or by using a separate 254.Fl mask 255option. 256If the mask is not specified, it will default to the mask for that network 257class (A, B or C; see 258.Xr inet 4 ) . 259See the 260.Sx EXAMPLES 261section below. 262.Pp 263The 264.Xr mountd 8 265utility can be made to re-read the 266.Nm 267file by sending it a hangup signal as follows: 268.Bd -literal -offset indent 269/etc/rc.d/mountd reload 270.Ed 271.Pp 272After sending the 273.Dv SIGHUP , 274check the 275.Xr syslogd 8 276output to see whether 277.Xr mountd 8 278logged any parsing errors in the 279.Nm 280file. 281.Sh FILES 282.Bl -tag -width /etc/exports -compact 283.It Pa /etc/exports 284the default remote mount-point file 285.El 286.Sh EXAMPLES 287.Bd -literal -offset indent 288/usr /usr/local -maproot=0:10 friends 289/usr -maproot=daemon grumpy.cis.uoguelph.ca 131.104.48.16 290/usr -ro -mapall=nobody 291/u -maproot=bin: -network 131.104.48 -mask 255.255.255.0 292/a -network 192.168.0/24 293/u2 -maproot=root friends 294/u2 -alldirs -network cis-net -mask cis-mask 295/cdrom -alldirs,quiet,ro -network 192.168.33.0 -mask 255.255.255.0 296.Ed 297.Pp 298Given that 299.Pa /usr , 300.Pa /u , 301.Pa /a 302and 303.Pa /u2 304are 305local filesystem mount points, the above example specifies the following: 306.Pp 307The file system rooted at 308.Pa /usr 309is exported to hosts 310.Em friends 311where friends is specified in the netgroup file 312with users mapped to their remote credentials and 313root mapped to UID 0 and group 10. 314It is exported read-write and the hosts in 315.Dq friends 316can mount either 317.Pa /usr 318or 319.Pa /usr/local . 320It is exported to 321.Em 131.104.48.16 322and 323.Em grumpy.cis.uoguelph.ca 324with users mapped to their remote credentials and 325root mapped to the user and groups associated with 326.Dq daemon ; 327it is exported to the rest of the world as read-only with 328all users mapped to the user and groups associated with 329.Dq nobody . 330.Pp 331The file system rooted at 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 339The file system rooted at 340.Pa /u2 341is exported to the hosts in 342.Dq friends 343with root mapped to UID and groups 344associated with 345.Dq root ; 346it is exported to all hosts on network 347.Dq cis-net 348allowing mounts at any 349directory within /u2. 350.Pp 351The file system rooted at 352.Pa /a 353is exported to the network 192.168.0.0, with a netmask of 255.255.255.0. 354However, the netmask length in the entry for 355.Pa /a 356is not specified through a 357.Fl mask 358option, but through the 359.Li / Ns Ar prefix 360notation. 361.Pp 362The filesystem rooted at 363.Pa /cdrom 364will exported read-only to the entire network 192.168.33.0/24, including 365all its subdirectories. 366Since 367.Pa /cdrom 368is the conventional mountpoint for a CD-ROM device, this export will 369fail if no CD-ROM medium is currently mounted there since that line 370would then attempt to export a subdirectory of the root filesystem 371with the 372.Fl alldirs 373option which is not allowed. 374The 375.Fl quiet 376option will then suppress the error message for this condition that 377would normally be syslogged. 378As soon as an actual CD-ROM is going to be mounted, 379.Xr mount 8 380will notify 381.Xr mountd 8 382about this situation, and the 383.Pa /cdrom 384filesystem will be exported as intended. 385Note that without using the 386.Fl alldirs 387option, the export would always succeed. 388While there is no CD-ROM medium mounted under 389.Pa /cdrom , 390it would export the (normally empty) directory 391.Pa /cdrom 392of the root filesystem instead. 393.Sh SEE ALSO 394.Xr netgroup 5 , 395.Xr mountd 8 , 396.Xr nfsd 8 , 397.Xr showmount 8 398.Sh BUGS 399The export options are tied to the local mount points in the kernel and 400must be non-contradictory for any exported subdirectory of the local 401server mount point. 402It is recommended that all exported directories within the same server 403filesystem be specified on adjacent lines going down the tree. 404You cannot specify a hostname that is also the name of a netgroup. 405Specifying the full domain specification for a hostname can normally 406circumvent the problem. 407