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 December 3, 2009 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 or the NFSv4 tree root 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 or the NFSv4 tree root 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 three 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 third form has the string ``V4:'' followed by a single absolute path 85name, to specify the NFSv4 tree root. 86The pathnames must not have any symbolic links in them and should not have 87any 88.Dq Pa \&. 89or 90.Dq Pa .. 91components. 92Mount points for a file system may appear on multiple lines each with 93different sets of hosts and export options. 94.Pp 95The second component of a line specifies how the file system is to be 96exported to the host set. 97The option flags specify whether the file system 98is exported read-only or read-write and how the client UID is mapped to 99user credentials on the server. 100For the NFSv4 tree root, the only option that can be specified in this 101section is 102.Fl sec . 103.Pp 104Export options are specified as follows: 105.Pp 106.Sm off 107.Fl maproot Li = Sy user 108.Sm on 109The credential of the specified user is used for remote access by root. 110The credential includes all the groups to which the user is a member 111on the local machine (see 112.Xr id 1 ) . 113The user may be specified by name or number. 114.Pp 115.Sm off 116.Fl maproot Li = Sy user:group1:group2:... 117.Sm on 118The colon separated list is used to specify the precise credential 119to be used for remote access by root. 120The elements of the list may be either names or numbers. 121Note that user: should be used to distinguish a credential containing 122no groups from a complete credential for that user. 123.Pp 124.Sm off 125.Fl mapall Li = Sy user 126.Sm on 127or 128.Sm off 129.Fl mapall Li = Sy user:group1:group2:... 130.Sm on 131specifies a mapping for all client UIDs (including root) 132using the same semantics as 133.Fl maproot . 134.Pp 135The option 136.Fl r 137is a synonym for 138.Fl maproot 139in an effort to be backward compatible with older export file formats. 140.Pp 141In the absence of 142.Fl maproot 143and 144.Fl mapall 145options, remote accesses by root will result in using a credential of -2:-2. 146All other users will be mapped to their remote credential. 147If a 148.Fl maproot 149option is given, 150remote access by root will be mapped to that credential instead of -2:-2. 151If a 152.Fl mapall 153option is given, 154all users (including root) will be mapped to that credential in 155place of their own. 156.Pp 157.Sm off 158.Fl sec Li = Sy flavor1:flavor2... 159.Sm on 160specifies a colon separated list of acceptable security flavors to be 161used for remote access. 162Supported security flavors are sys, krb5, krb5i and krb5p. 163If multiple flavors are listed, they should be ordered with the most 164preferred flavor first. 165If this option is not present, 166the default security flavor list of just sys is used. 167.Pp 168The 169.Fl ro 170option specifies that the file system should be exported read-only 171(default read/write). 172The option 173.Fl o 174is a synonym for 175.Fl ro 176in an effort to be backward compatible with older export file formats. 177.Pp 178.Tn WebNFS 179exports strictly according to the spec (RFC 2054 and RFC 2055) can 180be done with the 181.Fl public 182flag. 183However, this flag in itself allows r/w access to all files in 184the file system, not requiring reserved ports and not remapping UIDs. 185It 186is only provided to conform to the spec, and should normally not be used. 187For a 188.Tn WebNFS 189export, 190use the 191.Fl webnfs 192flag, which implies 193.Fl public , 194.Sm off 195.Fl mapall No = Sy nobody 196.Sm on 197and 198.Fl ro . 199Note that only one file system can be 200.Tn WebNFS 201exported on a server. 202.Pp 203A 204.Sm off 205.Fl index No = Pa file 206.Sm on 207option can be used to specify a file whose handle will be returned if 208a directory is looked up using the public filehandle 209.Pq Tn WebNFS . 210This is to mimic the behavior of URLs. 211If no 212.Fl index 213option is specified, a directory filehandle will be returned as usual. 214The 215.Fl index 216option only makes sense in combination with the 217.Fl public 218or 219.Fl webnfs 220flags. 221.Pp 222Specifying the 223.Fl quiet 224option will inhibit some of the syslog diagnostics for bad lines in 225.Pa /etc/exports . 226This can be useful to avoid annoying error messages for known possible 227problems (see 228.Sx EXAMPLES 229below). 230.Pp 231The third component of a line specifies the host set to which the line applies. 232The set may be specified in three ways. 233The first way is to list the host name(s) separated by white space. 234(Standard Internet 235.Dq dot 236addresses may be used in place of names.) 237The second way is to specify a 238.Dq netgroup 239as defined in the 240.Pa netgroup 241file (see 242.Xr netgroup 5 ) . 243The third way is to specify an Internet subnetwork using a network and 244network mask that is defined as the set of all hosts with addresses within 245the subnetwork. 246This latter approach requires less overhead within the 247kernel and is recommended for cases where the export line refers to a 248large number of clients within an administrative subnet. 249.Pp 250The first two cases are specified by simply listing the name(s) separated 251by whitespace. 252All names are checked to see if they are 253.Dq netgroup 254names 255first and are assumed to be hostnames otherwise. 256Using the full domain specification for a hostname can normally 257circumvent the problem of a host that has the same name as a netgroup. 258The third case is specified by the flag 259.Sm off 260.Fl network Li = Sy netname Op Li / Ar prefixlength 261.Sm on 262and optionally 263.Sm off 264.Fl mask No = Sy netmask . 265.Sm on 266The netmask may be specified either by attaching a 267.Ar prefixlength 268to the 269.Fl network 270option, or by using a separate 271.Fl mask 272option. 273If the mask is not specified, it will default to the mask for that network 274class (A, B or C; see 275.Xr inet 4 ) . 276See the 277.Sx EXAMPLES 278section below. 279.Pp 280Scoped IPv6 address must carry scope identifier as documented in 281.Xr inet6 4 . 282For example, 283.Dq Li fe80::%re2/10 284is used to specify 285.Li fe80::/10 286on 287.Li re2 288interface. 289.Pp 290For the third form which specifies the NFSv4 tree root, the directory path 291specifies the location within the server's file system tree which is the 292root of the NFSv4 tree. 293All entries of this form must specify the same directory path. 294This location can be any directory and does not 295need to be within an exported file system. If it is not in an exported 296file system, a very limited set of operations are permitted, so that an 297NFSv4 client can traverse the tree to an exported file system. 298Although parts of the NFSv4 tree can be non-exported, the entire NFSv4 tree 299must consist of local file systems capable of being exported via NFS. 300NFSv4 does not use the mount protocol and does permit clients to cross server 301mount point boundaries, although not all clients are capable of crossing the 302mount points. 303.Pp 304The 305.Fl sec 306option on these line(s) specifies what security flavors may be used for 307NFSv4 operations that do not use file handles. Since these operations 308(SetClientID, SetClientIDConfirm, Renew, DelegPurge and ReleaseLockOnwer) 309allocate/modify state in the server, it is possible to restrict some clients to 310the use of the krb5[ip] security flavors, via this option. 311See the 312.Sx EXAMPLES 313section below. 314This third form is meaningless for NFSv2 and NFSv3 and is ignored for them. 315.Pp 316The 317.Xr mountd 8 318utility can be made to re-read the 319.Nm 320file by sending it a hangup signal as follows: 321.Bd -literal -offset indent 322/etc/rc.d/mountd reload 323.Ed 324.Pp 325After sending the 326.Dv SIGHUP , 327check the 328.Xr syslogd 8 329output to see whether 330.Xr mountd 8 331logged any parsing errors in the 332.Nm 333file. 334.Sh FILES 335.Bl -tag -width /etc/exports -compact 336.It Pa /etc/exports 337the default remote mount-point file 338.El 339.Sh EXAMPLES 340.Bd -literal -offset indent 341/usr /usr/local -maproot=0:10 friends 342/usr -maproot=daemon grumpy.cis.uoguelph.ca 131.104.48.16 343/usr -ro -mapall=nobody 344/u -maproot=bin: -network 131.104.48 -mask 255.255.255.0 345/a -network 192.168.0/24 346/a -network 3ffe:1ce1:1:fe80::/64 347/u2 -maproot=root friends 348/u2 -alldirs -network cis-net -mask cis-mask 349/cdrom -alldirs,quiet,ro -network 192.168.33.0 -mask 255.255.255.0 350/private -sec=krb5i 351/secret -sec=krb5p 352V4: / -sec=krb5:krb5i:krb5p -network 131.104.48 -mask 255.255.255.0 353V4: / -sec=sys:krb5:krb5i:krb5p grumpy.cis.uoguelph.ca 354.Ed 355.Pp 356Given that 357.Pa /usr , /u , /a 358and 359.Pa /u2 360are 361local file system mount points, the above example specifies the following: 362.Pp 363The file system rooted at 364.Pa /usr 365is exported to hosts 366.Em friends 367where friends is specified in the netgroup file 368with users mapped to their remote credentials and 369root mapped to UID 0 and group 10. 370It is exported read-write and the hosts in 371.Dq friends 372can mount either 373.Pa /usr 374or 375.Pa /usr/local . 376It is exported to 377.Em 131.104.48.16 378and 379.Em grumpy.cis.uoguelph.ca 380with users mapped to their remote credentials and 381root mapped to the user and groups associated with 382.Dq daemon ; 383it is exported to the rest of the world as read-only with 384all users mapped to the user and groups associated with 385.Dq nobody . 386.Pp 387The file system rooted at 388.Pa /u 389is exported to all hosts on the subnetwork 390.Em 131.104.48 391with root mapped to the UID for 392.Dq bin 393and with no group access. 394.Pp 395The file system rooted at 396.Pa /u2 397is exported to the hosts in 398.Dq friends 399with root mapped to UID and groups 400associated with 401.Dq root ; 402it is exported to all hosts on network 403.Dq cis-net 404allowing mounts at any 405directory within /u2. 406.Pp 407The file system rooted at 408.Pa /a 409is exported to the network 192.168.0.0, with a netmask of 255.255.255.0. 410However, the netmask length in the entry for 411.Pa /a 412is not specified through a 413.Fl mask 414option, but through the 415.Li / Ns Ar prefix 416notation. 417.Pp 418The file system rooted at 419.Pa /a 420is also exported to the IPv6 network 421.Li 3ffe:1ce1:1:fe80:: 422address, using the upper 64 bits as the prefix. 423Note that, unlike with IPv4 network addresses, the specified network 424address must be complete, and not just contain the upper bits. 425With IPv6 addresses, the 426.Fl mask 427option must not be used. 428.Pp 429The file system rooted at 430.Pa /cdrom 431will be exported read-only to the entire network 192.168.33.0/24, including 432all its subdirectories. 433Since 434.Pa /cdrom 435is the conventional mountpoint for a CD-ROM device, this export will 436fail if no CD-ROM medium is currently mounted there since that line 437would then attempt to export a subdirectory of the root file system 438with the 439.Fl alldirs 440option which is not allowed. 441The 442.Fl quiet 443option will then suppress the error message for this condition that 444would normally be syslogged. 445As soon as an actual CD-ROM is going to be mounted, 446.Xr mount 8 447will notify 448.Xr mountd 8 449about this situation, and the 450.Pa /cdrom 451file system will be exported as intended. 452Note that without using the 453.Fl alldirs 454option, the export would always succeed. 455While there is no CD-ROM medium mounted under 456.Pa /cdrom , 457it would export the (normally empty) directory 458.Pa /cdrom 459of the root file system instead. 460.Pp 461The file system rooted at 462.Pa /private 463will be exported using Kerberos 5 authentication and will require 464integrity protected messages for all accesses. 465The file system rooted at 466.Pa /secret 467will also be exported using Kerberos 5 authentication and all messages 468used to access it will be encrypted. 469.Pp 470For the experimental server, the NFSv4 tree is rooted at ``/'', 471and any client within the 131.104.48 subnet is permitted to perform NFSv4 state 472operations on the server, so long as valid Kerberos credentials are provided. 473The machine grumpy.cis.uoguelph.ca is permitted to perform NFSv4 state 474operations on the server using AUTH_SYS credentials, as well as Kerberos ones. 475.Sh SEE ALSO 476.Xr nfsv4 4 , 477.Xr netgroup 5 , 478.Xr mountd 8 , 479.Xr nfsd 8 , 480.Xr showmount 8 481.Sh BUGS 482The export options are tied to the local mount points in the kernel and 483must be non-contradictory for any exported subdirectory of the local 484server mount point. 485It is recommended that all exported directories within the same server 486file system be specified on adjacent lines going down the tree. 487You cannot specify a hostname that is also the name of a netgroup. 488Specifying the full domain specification for a hostname can normally 489circumvent the problem. 490