1.\" $NetBSD: exports.5,v 1.39 2024/03/29 22:50:27 uwe 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 March 27, 2024 33.Dt EXPORTS 5 34.Os 35.Sh NAME 36.Nm exports 37.Nd exported filesystem mount points for 38.Tn NFS 39mount requests 40.Sh DESCRIPTION 41The 42.Nm 43file on an 44.Tn NFS 45server lists filesystems to be exported to 46.Tn NFS 47clients. 48It is read and applied by 49.Xr mountd 8 50on start and on 51.Dv SIGHUP . 52.Pp 53Each entry in 54.Nm 55is a line with a list of directories followed by a list of hosts, 56netgroups, and options, separated by spaces or tabs: 57.Pp 58.D1 Li / Ns Ar dir Li ... Oo Ar host | Ar netgroup | Fl Ar option Oc Li ... 59.Pp 60All directories in a single line must live in the same filesystem, 61which is exported to the hosts and netgroups listed, according to the 62options specified. 63Exported directories must not have pathname components that are 64symbolic links, 65.Ql \&. , 66or 67.Ql \&.. . 68.Pp 69.Bf -symbolic 70Warning: 71Exporting a directory exposes the 72.Em entire 73contents of the filesystem that the directory lives in to 74.Tn NFS 75clients. 76.Ef 77This happens even if an exported directory is not the root directory of 78a filesystem on the server. 79.Tn NFS 80clients are only prevented from access to files and directories on 81filesystems that are 82.Em not 83exported at all. 84.Pp 85.Bf -symbolic 86Warning: 87Access control is only by network address. 88.Ef 89.Tn NFS 90servers with any non-public data should be exposed only to restricted 91or firewalled networks with ingress filtering. 92There is no authentication or encryption to make it safe for 93restricting access on the open internet. 94.Pp 95Blank lines are ignored. 96Text beginning with 97.Ql # 98until the end of line is ignored as a comment. 99Each line ending with 100.Ql \e 101has the next line appended, without the 102.Ql \e , 103as a continuation line. 104Characters can be escaped with 105.Ql \e . 106.Pp 107All directories, which begin with 108.Ql / , 109must come before any hosts, netgroups, or options on a line. 110Options begin with 111.Ql - . 112All other items on an export line are interpreted either as netgroups 113.Po see 114.Xr netgroup 5 115.Pc 116or as hosts, which can be either names, as in example.com, or numbers, 117as in 192.0.2.123 or 2001:db8:1234:abcd::42. 118Sets of hosts in a contiguous network range can be specified with the 119.Fl network 120option. 121.Pp 122The same filesystem may be exported on multiple lines with different 123options to different sets of hosts, as long as it is exported at most 124once to each host, netgroup, or network. 125.Pp 126Export lines with no hosts, netgroups, or 127.Fl network 128options are exported to 129.Em any 130hosts on the network, with no access control. 131.Pp 132Supported export options: 133.Bl -tag -width Fl 134.It Fl alldirs 135Allow mount requests from clients at any point within the filesystem, 136including regular files. 137Only the root directory of the filesystem should be specified on the 138line. 139.Pp 140Note that omitting the 141.Fl alldirs 142option should not be used as a security measure to make clients mount 143only those subdirectories that they should have access to. 144A client 145can still access the whole filesystem via individual RPCs if it 146wanted to, even if just one subdirectory has been mounted. 147.Sm off 148.It Fl maproot Li = Ar user 149.Sm on 150The credential of the specified user is used for remote access by root. 151The credential includes all the groups to which the user is a member 152on the local machine 153.Po see 154.Xr id 1 155.Pc . 156The user may be specified by name or number. 157.Sm off 158.It Fl maproot Li = Ar user\^ Li \&: Op Ar group1\^ Li \&: group2\^ Li \&: Ar ... 159.Sm on 160The colon separated list is used to specify the precise credential 161to be used for remote access by root. 162The elements of the list may be either names or numbers. 163Note that 164.Sq Ar user\^ Ns Li \&: 165(with the trailing colon) 166should be used to distinguish a credential containing no groups from a 167complete credential for that user. 168.Sm off 169.It Fl mapall Li = Ar user 170.It Fl mapall Li = Ar user\^ Li \&: Op Ar group1\^ Li \&: Ar group2\^ Li \&: Ar ... 171.Sm on 172Mapping for all client uids (including root) 173using the same semantics as 174.Fl maproot . 175.It Fl r Ar user 176.It Fl r Ar user\^ Ns Li \&: Ns Op Ar group1\^ Ns Li \&: Ns Ar group2\^ Ns Li \&: Ns Ar ... 177Synonym for 178.Fl maproot , 179for compatibility with older export file formats. 180.Pp 181.Em Note : 182Not a synonym for the read-only option 183.Fl ro . 184.El 185.Pp 186In the absence of 187.Fl maproot 188and 189.Fl mapall 190options, remote accesses by root will result in using a credential of -2:-2. 191All other users will be mapped to their remote credential. 192If a 193.Fl maproot 194option is given, 195remote access by root will be mapped to that credential instead of -2:-2. 196If a 197.Fl mapall 198option is given, 199all users (including root) will be mapped to that credential in 200place of their own. 201.Bl -tag -width Fl 202.It Fl kerb 203Specifies that the Kerberos authentication server should be 204used to authenticate and map client credentials. 205.Sy This option is currently not implemented. 206.It Fl ro 207Export filesystem read-only. 208Clients will be forbidden to change or write to anything in the 209filesystem 210.Po 211except for named pipes, sockets, and device nodes, where 212write semantics is client-side anyway 213.Pc . 214.It Fl o 215Synonym for 216.Fl ro 217for compatibility with older export file formats. 218.It Fl noresvport 219Allow NFS RPC calls for the filesystem to come from non-reserved 220ports. 221Normally, clients are required to use reserved ports for operations. 222Using this option decreases the security of your system. 223.\" XXX ^ Not really... 224.It Fl noresvmnt 225Allow mount RPC requests for the filesystem to come from non-reserved 226ports. 227Normally, clients are required to use reserved ports for mount requests. 228Using this option decreases the security of your system. 229.\" XXX ^ Not really... 230.It Fl webnfs 231(WebNFS) 232Enables WebNFS export, equivalent to combining 233.Fl public , 234.Fl mapall=nobody , 235and 236.Fl ro . 237.It Fl public 238(WebNFS) 239Enables WebNFS export strictly according to the spec, 240RFC 2054 and RFC 2055. 241This implies: 242.Bl -bullet -compact 243.It 244read/write access to all files in the filesystem 245.It 246not requiring reserved ports 247.Pq Fl noresvport , Fl noresvmnt 248.It 249not remapping uids 250.El 251.Pp 252.Bf -symbolic 253Warning: 254.Fl public 255is only provided to conform to the spec, and should normally 256not be used. 257.Ef 258For a WebNFS export, 259use the 260.Fl webnfs 261flag. 262.It Fl index Ns Li = Ns Ar file 263(WebNFS) 264File whose handle will be returned if 265a directory is looked up using the public filehandle. 266This is to mimic the behavior of URLs. 267If no 268.Fl index 269option is specified, a directory filehandle will be returned as usual. 270.Pp 271The 272.Fl index 273option only makes sense in combination with the 274.Fl public 275or 276.Fl webnfs 277flags. 278.El 279.Pp 280.Bf -symbolic 281Warning: exporting a filesystem both using WebNFS and read/write in 282the normal way to other hosts should be avoided in an environment 283that is vulnerable to IP spoofing. 284.Ef 285.\" XXX Isn't this an issue for _all_ read/write exports, not just 286.\" WebNFS ones? 287WebNFS enables any client to get filehandles to the exported filesystem. 288Using IP spoofing, a client could then pretend to be a host to which 289the same filesystem was exported read/write, and use the handle to 290gain access to that filesystem. 291.Bl -tag -width Fl 292.Sm off 293.It Fl network Li = Ar netname Op Li / Ar prefixlength 294.Sm on 295Export the filesystem to all hosts in the specified network. 296.Pp 297This approach to identifying hosts requires less overhead within the 298kernel and is recommended for cases where the export line refers to a 299large number of clients within an administrative subnet. 300.Pp 301The netmask may be specified either by 302.Ar prefixlength , 303or 304.Pq for IPv4 networks only 305by using a separate 306.Fl mask 307option. 308If the mask is not specified, it will default to the mask for that network 309class 310.Po 311A, B or C; see 312.Xr inet 4 313.Pc . 314.Pp 315Scoped IPv6 address must carry a scope identifier as documented in 316.Xr inet6 4 . 317For example, 318.Ql fe80::%ne2/10 319is used to specify 320.Ql fe80::/10 321on 322.Ql ne2 323interface. 324.Sm off 325.It Fl mask No = Ar netmask 326.Sm on 327(IPv4-only) 328Netmask for 329.Fl network 330options with no 331.Ar prefixlength . 332.El 333.Sh FILES 334.Bl -tag -width Pa -compact 335.It Pa /etc/exports 336The default remote mount-point file. 337.El 338.Pp 339If you have modified the 340.Pa /etc/exports 341file, send the mountd process a 342.Dv SIGHUP 343to make it re-read it: 344.Pp 345.Dl "kill -HUP $(cat /var/run/mountd.pid)" 346.Sh EXAMPLES 347.Bd -literal -offset indent 348/usr /usr/local -maproot=0:10 friends 349/usr -maproot=daemon grumpy.cis.uoguelph.ca 131.104.48.16 350/usr -ro -mapall=nobody 351/u -maproot=bin: -network 131.104.48 -mask 255.255.255.0 352/a -network 192.168.0/24 353/a -network 3ffe:1ce1:1:fe80::/64 354/u2 -maproot=root friends 355/u2 -alldirs -kerb -network cis-net -mask cis-mask 356.Ed 357.Pp 358Given that 359.Pa /usr , 360.Pa /u , 361and 362.Pa /u2 363are local filesystem mount points, the above example specifies the 364following: 365.Bl -tag -width ".Pa /usr" 366.It Pa /usr 367is exported to hosts 368.Ql friends 369where 370.Ql friends 371is specified in the 372.Xr netgroup 5 373file with users mapped to their remote credentials and 374root mapped to uid 0 and group 10. 375It is exported read-write and the hosts in 376.Ql friends 377can mount either 378.Pa /usr 379or 380.Pa /usr/local . 381.Pp 382It is also exported to 383.Ql 131.104.48.16 384and 385.Ql grumpy.cis.uoguelph.ca 386with users mapped to their remote credentials and 387root mapped to the user and groups associated with 388.Ql daemon . 389.Pp 390It is also exported to the rest of the world as read-only with 391all users mapped to the user and groups associated with 392.Ql nobody . 393.It Pa /u 394is exported to all hosts on the subnetwork 395.Ql 131.104.48 396with root mapped to the uid for 397.Ql bin 398and with no group access. 399.It Pa /u2 400is exported to the hosts in 401.Ql friends 402with root mapped to uid and groups associated with 403.Ql root ; 404it is exported to all hosts on network 405.Ql cis-net 406allowing mounts at any 407directory within 408.Pa /u2 409and mapping all uids to credentials for the principal 410that is authenticated by a Kerberos ticket. 411.Pq Sy Kerberos not implemented. 412.It Pa /a 413is exported to the network 414.Ql 192.168.0.0 , 415with a netmask of 416.Ql 255.255.255.0 . 417However, the netmask in the entry for 418.Pa /a 419is not specified through a 420.Fl mask 421option, but through the 422.Li / Ns Ar prefixlen 423notation. 424.It Pa /a 425is also exported to the IPv6 network 426.Ql 3ffe:1ce1:1:fe80:: 427address, using the upper 64 bits as the prefix. 428Note that, unlike with IPv4 network addresses, the specified network 429address must be complete, and not just contain the upper bits. 430With IPv6 addresses, the 431.Fl mask 432option must not be used. 433.El 434.Sh SEE ALSO 435.Xr netgroup 5 , 436.Xr mountd 8 , 437.Xr nfsd 8 , 438.Xr showmount 8 439.Rs 440.%T NFS: Network File System Protocol Specification 441.%R RFC 1094 442.%I IETF Network Working Group 443.%O Appendix A 444.%U https://datatracker.ietf.org/doc/html/rfc1094#appendix-A.1 445.Re 446.Rs 447.%A B. Callaghan 448.%A B. Pawlowski 449.%A P. Staubach 450.%T NFS Version 3 Protocol Specification 451.%R RFC 1813 452.%I IETF Network Working Group 453.%O Appendix I 454.%U https://datatracker.ietf.org/doc/html/rfc1813#section-5.0 455.Re 456.Sh CAVEATS 457Don't re-export NFS-mounted filesystems unless you are sure of the 458implications. 459NFS has some assumptions about the characteristics of the file 460systems being exported, e.g. when timestamps are updated. 461Re-exporting should work to some extent and can even be useful in 462some cases, but don't expect it works as well as with local file 463systems. 464.Pp 465Filesystems that provide a namespace for a subtree of another 466filesystem such as nullfs 467.Pq Xr mount_null 8 468and umapfs 469.Pq Xr mount_umap 8 470.Em do not 471restrict 472.Tn NFS 473clients to that namespace, so they cannot be used to securely limit 474.Tn NFS 475clients to a subtree of a filesystem. 476If you want to export one subtree and prevent access to other subtrees, 477the exported subtree must be on its own filesystem on the server. 478.Sh BUGS 479The export options are tied to the local mount points in the kernel and 480must be non-contradictory for any exported subdirectory of the local 481server mount point. 482.\" XXX Explain what `contradictory' means here and give some positive 483.\" and negative examples. 484It is recommended that all exported directories within the same server 485filesystem be specified on adjacent lines going down the tree. 486You cannot specify a hostname that is also the name of a netgroup. 487Specifying the full domain specification for a hostname can normally 488circumvent the problem. 489