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 152.Sm off 153.Fl sec Li = Sy flavor1:flavor2... 154.Sm on 155specifies a colon separated list of acceptable security flavors to be 156used for remote access. 157Supported security flavors are sys, krb5, krb5i and krb5p. 158If multiple flavors are listed, they should be ordered with the most 159preferred flavor first. 160If this option is not present, 161the default security flavor list of just sys is used. 162.Pp 163The 164.Fl ro 165option specifies that the file system should be exported read-only 166(default read/write). 167The option 168.Fl o 169is a synonym for 170.Fl ro 171in an effort to be backward compatible with older export file formats. 172.Pp 173.Tn WebNFS 174exports strictly according to the spec (RFC 2054 and RFC 2055) can 175be done with the 176.Fl public 177flag. 178However, this flag in itself allows r/w access to all files in 179the file system, not requiring reserved ports and not remapping UIDs. 180It 181is only provided to conform to the spec, and should normally not be used. 182For a 183.Tn WebNFS 184export, 185use the 186.Fl webnfs 187flag, which implies 188.Fl public , 189.Sm off 190.Fl mapall No = Sy nobody 191.Sm on 192and 193.Fl ro . 194Note that only one file system can be 195.Tn WebNFS 196exported on a server. 197.Pp 198A 199.Sm off 200.Fl index No = Pa file 201.Sm on 202option can be used to specify a file whose handle will be returned if 203a directory is looked up using the public filehandle 204.Pq Tn WebNFS . 205This is to mimic the behavior of URLs. 206If no 207.Fl index 208option is specified, a directory filehandle will be returned as usual. 209The 210.Fl index 211option only makes sense in combination with the 212.Fl public 213or 214.Fl webnfs 215flags. 216.Pp 217Specifying the 218.Fl quiet 219option will inhibit some of the syslog diagnostics for bad lines in 220.Pa /etc/exports . 221This can be useful to avoid annoying error messages for known possible 222problems (see 223.Sx EXAMPLES 224below). 225.Pp 226The third component of a line specifies the host set to which the line applies. 227The set may be specified in three ways. 228The first way is to list the host name(s) separated by white space. 229(Standard Internet 230.Dq dot 231addresses may be used in place of names.) 232The second way is to specify a 233.Dq netgroup 234as defined in the 235.Pa netgroup 236file (see 237.Xr netgroup 5 ) . 238The third way is to specify an Internet subnetwork using a network and 239network mask that is defined as the set of all hosts with addresses within 240the subnetwork. 241This latter approach requires less overhead within the 242kernel and is recommended for cases where the export line refers to a 243large number of clients within an administrative subnet. 244.Pp 245The first two cases are specified by simply listing the name(s) separated 246by whitespace. 247All names are checked to see if they are 248.Dq netgroup 249names 250first and are assumed to be hostnames otherwise. 251Using the full domain specification for a hostname can normally 252circumvent the problem of a host that has the same name as a netgroup. 253The third case is specified by the flag 254.Sm off 255.Fl network Li = Sy netname Op Li / Ar prefixlength 256.Sm on 257and optionally 258.Sm off 259.Fl mask No = Sy netmask . 260.Sm on 261The netmask may be specified either by attaching a 262.Ar prefixlength 263to the 264.Fl network 265option, or by using a separate 266.Fl mask 267option. 268If the mask is not specified, it will default to the mask for that network 269class (A, B or C; see 270.Xr inet 4 ) . 271See the 272.Sx EXAMPLES 273section below. 274.Pp 275Scoped IPv6 address must carry scope identifier as documented in 276.Xr inet6 4 . 277For example, 278.Dq Li fe80::%re2/10 279is used to specify 280.Li fe80::/10 281on 282.Li re2 283interface. 284.Pp 285The 286.Xr mountd 8 287utility can be made to re-read the 288.Nm 289file by sending it a hangup signal as follows: 290.Bd -literal -offset indent 291/etc/rc.d/mountd reload 292.Ed 293.Pp 294After sending the 295.Dv SIGHUP , 296check the 297.Xr syslogd 8 298output to see whether 299.Xr mountd 8 300logged any parsing errors in the 301.Nm 302file. 303.Sh FILES 304.Bl -tag -width /etc/exports -compact 305.It Pa /etc/exports 306the default remote mount-point file 307.El 308.Sh EXAMPLES 309.Bd -literal -offset indent 310/usr /usr/local -maproot=0:10 friends 311/usr -maproot=daemon grumpy.cis.uoguelph.ca 131.104.48.16 312/usr -ro -mapall=nobody 313/u -maproot=bin: -network 131.104.48 -mask 255.255.255.0 314/a -network 192.168.0/24 315/a -network 3ffe:1ce1:1:fe80::/64 316/u2 -maproot=root friends 317/u2 -alldirs -network cis-net -mask cis-mask 318/cdrom -alldirs,quiet,ro -network 192.168.33.0 -mask 255.255.255.0 319/private -sec=krb5i 320/secret -sec=krb5p 321.Ed 322.Pp 323Given that 324.Pa /usr , /u , /a 325and 326.Pa /u2 327are 328local file system mount points, the above example specifies the following: 329.Pp 330The file system rooted at 331.Pa /usr 332is exported to hosts 333.Em friends 334where friends is specified in the netgroup file 335with users mapped to their remote credentials and 336root mapped to UID 0 and group 10. 337It is exported read-write and the hosts in 338.Dq friends 339can mount either 340.Pa /usr 341or 342.Pa /usr/local . 343It is exported to 344.Em 131.104.48.16 345and 346.Em grumpy.cis.uoguelph.ca 347with users mapped to their remote credentials and 348root mapped to the user and groups associated with 349.Dq daemon ; 350it is exported to the rest of the world as read-only with 351all users mapped to the user and groups associated with 352.Dq nobody . 353.Pp 354The file system rooted at 355.Pa /u 356is exported to all hosts on the subnetwork 357.Em 131.104.48 358with root mapped to the UID for 359.Dq bin 360and with no group access. 361.Pp 362The file system rooted at 363.Pa /u2 364is exported to the hosts in 365.Dq friends 366with root mapped to UID and groups 367associated with 368.Dq root ; 369it is exported to all hosts on network 370.Dq cis-net 371allowing mounts at any 372directory within /u2. 373.Pp 374The file system rooted at 375.Pa /a 376is exported to the network 192.168.0.0, with a netmask of 255.255.255.0. 377However, the netmask length in the entry for 378.Pa /a 379is not specified through a 380.Fl mask 381option, but through the 382.Li / Ns Ar prefix 383notation. 384.Pp 385The file system rooted at 386.Pa /a 387is also exported to the IPv6 network 388.Li 3ffe:1ce1:1:fe80:: 389address, using the upper 64 bits as the prefix. 390Note that, unlike with IPv4 network addresses, the specified network 391address must be complete, and not just contain the upper bits. 392With IPv6 addresses, the 393.Fl mask 394option must not be used. 395.Pp 396The file system rooted at 397.Pa /cdrom 398will be exported read-only to the entire network 192.168.33.0/24, including 399all its subdirectories. 400Since 401.Pa /cdrom 402is the conventional mountpoint for a CD-ROM device, this export will 403fail if no CD-ROM medium is currently mounted there since that line 404would then attempt to export a subdirectory of the root file system 405with the 406.Fl alldirs 407option which is not allowed. 408The 409.Fl quiet 410option will then suppress the error message for this condition that 411would normally be syslogged. 412As soon as an actual CD-ROM is going to be mounted, 413.Xr mount 8 414will notify 415.Xr mountd 8 416about this situation, and the 417.Pa /cdrom 418file system will be exported as intended. 419Note that without using the 420.Fl alldirs 421option, the export would always succeed. 422While there is no CD-ROM medium mounted under 423.Pa /cdrom , 424it would export the (normally empty) directory 425.Pa /cdrom 426of the root file system instead. 427.Pp 428The file system rooted at 429.Pa /private 430will be exported using Kerberos 5 authentication and will require 431integrity protected messages for all accesses. 432The file system rooted at 433.Pa /secret 434will also be exported using Kerberos 5 authentication and all messages 435used to access it will be encrypted. 436.Sh SEE ALSO 437.Xr netgroup 5 , 438.Xr mountd 8 , 439.Xr nfsd 8 , 440.Xr showmount 8 441.Sh BUGS 442The export options are tied to the local mount points in the kernel and 443must be non-contradictory for any exported subdirectory of the local 444server mount point. 445It is recommended that all exported directories within the same server 446file system be specified on adjacent lines going down the tree. 447You cannot specify a hostname that is also the name of a netgroup. 448Specifying the full domain specification for a hostname can normally 449circumvent the problem. 450