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.Dd August 24, 2025 29.Dt EXPORTS 5 30.Os 31.Sh NAME 32.Nm exports 33.Nd define remote mount points for 34.Tn NFS 35mount requests 36.Sh SYNOPSIS 37.Nm 38.Sh DESCRIPTION 39The 40.Nm 41file specifies remote mount points for the 42.Tn NFS 43mount protocol per the 44.Tn NFS 45server specification; see 46.%T "Network File System Protocol Specification" , 47RFC1094, Appendix A and 48.%T "NFS: Network File System Version 3 Specification" , 49Appendix I. 50.Pp 51Each line in the file 52(other than comment lines that begin with a #) 53specifies the mount point(s) and export flags within one local server 54file system or the NFSv4 tree root for one or more hosts. 55A long line may be split over several lines by ending all but the 56last line with a backslash 57.Pq Ql \e . 58A host may be specified only once for each local file system or the NFSv4 tree 59root on the server and there may be only one default entry for each server 60file system that applies to all other hosts. 61The latter exports the file system to the 62.Dq world 63and should 64be used only when the file system contains public information. 65.Pp 66In a mount entry, 67the first field(s) specify the directory path(s) within a server file system 68that can be mounted on by the corresponding client(s). 69Note well that exporting a directory on the server does not guarantee that only 70files below the exported directory will be accessible. 71This is true even in the absence of the 72.Fl alldirs 73flag. 74To provide this guarantee, the exported directories must be local file system 75mount points on the server. 76For example, if one exports 77.Pa /home , 78and 79.Pa /home 80is not a file system mount point, then clients will be able to access arbitrary 81files on the root file system. 82As such, to avoid confusion with respect to what is exported, it may be prudent 83to limit exported directories to server local file system mount points. 84When exporting ZFS datasets with the 85.Sy sharenfs 86property, this is auomatically the case. 87If the 88.Fl alldirs 89flag is specified and 90the 91.Fl a 92command line option is specified for 93.Xr mountd 8 , 94the export will fail if the directory path is not a local file system 95mount point. 96.Pp 97There are three forms of the directory path specification. 98The first is to list all mount points as absolute 99directory paths separated by whitespace. 100This list of directory paths should be considered an 101.Dq administrative control , 102since it is only enforced by the 103.Xr mountd 8 104daemon and not the kernel. 105As such, it only applies to NFSv2 and NFSv3 mounts and only 106with respect to the client's use of the mount protocol. 107The second is to specify the pathname of the root of the file system 108followed by the 109.Fl alldirs 110flag; 111this form allows the host(s) to mount at any point within the file system, 112including regular files if the 113.Fl r 114option is used on 115.Xr mountd 8 . 116Because NFSv4 does not use the mount protocol, 117the 118.Dq administrative controls 119are not applied and all directories within this server 120file system are mountable via NFSv4 even if the 121.Fl alldirs 122flag has not been specified. 123The third form has the string ``V4:'' followed by a single absolute path 124name, to specify the NFSv4 tree root. 125This line does not export any file system, but simply marks where the root 126of the server's directory tree is for NFSv4 clients. 127The exported file systems for NFSv4 are specified via the other lines 128in the 129.Nm 130file in the same way as for NFSv2 and NFSv3. 131The pathnames must not have any symbolic links in them and should not have 132any 133.Dq Pa \&. 134or 135.Dq Pa .. 136components. 137Pathnames are decoded by 138.Xr strunvis 3 139allowing special characters to be included in the directory name(s). 140In particular, whitespace, such as embedded blanks in directory names 141can be handled. 142For example, a blank can be encoded as \(rs040. 143.Xr vis 1 144with the 145.Fl M 146option may be used to encode directory name(s) with embedded special 147characters. 148Mount points for a file system may appear on multiple lines each with 149different sets of hosts and export options. 150.Pp 151Note that, for NFSv4 exporting, there must be both one or more ``V4:'' line(s) 152and one or more line(s) exporting the file systems that are to be 153exported to NFSv4 clients. 154If there are multiple ``V4:'' lines, these lines must all specify the 155same root directory path, but with different options for different 156clients. 157These line(s) do not export any file system, but simply define the 158location of the ``root'' of the NFSv4 export subtree. 159The line(s) exporting the file systems should always 160specify the pathname of the root of a server file system 161and must include at least one line exporting the file system 162which is specified as the ``root'' by the ``V4:'' line(s). 163.Pp 164The second component of a line specifies how the file system is to be 165exported to the host set. 166The option flags specify whether the file system 167is exported read-only or read-write and how the client UID is mapped to 168user credentials on the server. 169For the NFSv4 tree root, the only options that can be specified in this 170section are ones related to security: 171.Fl sec , 172.Fl tls , 173.Fl tlscert 174and 175.Fl tlscertuser . 176.Pp 177Export options are specified as follows: 178.Pp 179.Sm off 180.Fl maproot Li = Sy user 181.Sm on 182The credential of the specified user is used for remote access by root. 183The credential includes all the groups to which the user is a member 184on the local machine (see 185.Xr id 1 ) . 186The user may be specified by name or number. 187The user string may be quoted, or use backslash escaping. 188.Pp 189.Sm off 190.Fl maproot Li = Sy user:group1:group2:... 191.Sm on 192The colon separated list is used to specify the precise credential 193to be used for remote access by root. 194The elements of the list may be either names or numbers. 195Note that 196.Cm user: 197should be used to specify a credential containing no groups, in which case the 198established credential will use 199.Ql nogroup , 200else 65533 201.Pq Dv GID_NOGROUP , 202as the fallback group 203.Pq a credential object must have at least one group internally . 204Using just 205.Cm user 206.Pq without colon at end 207falls into the 208.Sm off 209.Fl maproot Li = Sy user 210.Sm on 211case described above. 212The group names may be quoted, or use backslash escaping. 213.Pp 214.Sm off 215.Fl mapall Li = Sy user 216.Sm on 217or 218.Sm off 219.Fl mapall Li = Sy user:group1:group2:... 220.Sm on 221specifies a mapping for all client UIDs (including root) 222using the same semantics as 223.Fl maproot . 224.Pp 225The option 226.Fl r 227is a synonym for 228.Fl maproot 229in an effort to be backward compatible with older export file formats. 230.Pp 231In the absence of 232.Fl maproot 233and 234.Fl mapall 235options, remote accesses by root will result in using a credential of 65534:65533. 236All other users will be mapped to their remote credential. 237If a 238.Fl maproot 239option is given, 240remote access by root will be mapped to that credential instead of 65534:65533. 241If a 242.Fl mapall 243option is given, 244all users (including root) will be mapped to that credential in 245place of their own. 246.Pp 247.Sm off 248.Fl sec Li = Sy flavor1:flavor2... 249.Sm on 250specifies a colon separated list of acceptable security flavors to be 251used for remote access. 252Supported security flavors are sys, krb5, krb5i and krb5p. 253If multiple flavors are listed, they should be ordered with the most 254preferred flavor first. 255If this option is not present, 256the default security flavor list of just sys is used. 257.Pp 258The 259.Fl ro 260option specifies that the file system should be exported read-only 261(default read/write). 262The option 263.Fl o 264is a synonym for 265.Fl ro 266in an effort to be backward compatible with older export file formats. 267.Pp 268.Tn WebNFS 269exports strictly according to the spec (RFC 2054 and RFC 2055) can 270be done with the 271.Fl public 272flag. 273However, this flag in itself allows r/w access to all files in 274the file system, not requiring reserved ports and not remapping UIDs. 275It 276is only provided to conform to the spec, and should normally not be used. 277For a 278.Tn WebNFS 279export, 280use the 281.Fl webnfs 282flag, which implies 283.Fl public , 284.Sm off 285.Fl mapall No = Sy nobody 286.Sm on 287and 288.Fl ro . 289Note that only one file system can be 290.Tn WebNFS 291exported on a server. 292.Pp 293A 294.Sm off 295.Fl index No = Pa file 296.Sm on 297option can be used to specify a file whose handle will be returned if 298a directory is looked up using the public filehandle 299.Pq Tn WebNFS . 300This is to mimic the behavior of URLs. 301If no 302.Fl index 303option is specified, a directory filehandle will be returned as usual. 304The 305.Fl index 306option only makes sense in combination with the 307.Fl public 308or 309.Fl webnfs 310flags. 311.Pp 312The 313.Fl tls , 314.Fl tlscert 315and 316.Fl tlscertuser 317export options are used to require the client to use TLS for the mount(s) 318per RFC 9289. 319For NFS mounts using TLS to work, 320.Xr rpc.tlsservd 8 321must be running on the server. 322.Bd -filled -offset indent 323.Fl tls 324requires that the client use TLS. 325.br 326.Fl tlscert 327requires that the client use TLS and provide a verifiable X.509 certificate 328during TLS handshake. 329.br 330.Fl tlscertuser 331requires that the client use TLS and provide a verifiable X.509 certificate. 332The otherName component of the certificate's subjAltName must have a 333an OID of 1.3.6.1.4.1.2238.1.1.1 and a UTF8 string of the form 334.Dq user@domain . 335.Dq user@domain 336will be translated to the credentials of the specified user in the same 337manner as 338.Xr nfsuserd 8 , 339where 340.Dq user 341is normally a username is the server's password database and 342.Dq domain 343is the DNS domain name for the server. 344All RPCs will be performed using these credentials instead of the 345ones in the RPC header in a manner similar to 346.Sm off 347.Fl mapall Li = Sy user . 348.Sm on 349.Ed 350.Pp 351If none of these three flags are specified, TLS mounts are permitted but 352not required. 353.Pp 354Specifying the 355.Fl quiet 356option will inhibit some of the syslog diagnostics for bad lines in 357.Pa /etc/exports . 358This can be useful to avoid annoying error messages for known possible 359problems (see 360.Sx EXAMPLES 361below). 362.Pp 363The third component of a line specifies the host set to which the line applies. 364The set may be specified in three ways. 365The first way is to list the host name(s) separated by white space. 366(Standard Internet 367.Dq dot 368addresses may be used in place of names.) 369The second way is to specify a 370.Dq netgroup 371as defined in the 372.Pa netgroup 373file (see 374.Xr netgroup 5 ) . 375The third way is to specify an Internet subnetwork using a network and 376network mask that is defined as the set of all hosts with addresses within 377the subnetwork. 378This latter approach requires less overhead within the 379kernel and is recommended for cases where the export line refers to a 380large number of clients within an administrative subnet. 381.Pp 382The first two cases are specified by simply listing the name(s) separated 383by whitespace. 384All names are checked to see if they are 385.Dq netgroup 386names 387first and are assumed to be hostnames otherwise. 388Using the full domain specification for a hostname can normally 389circumvent the problem of a host that has the same name as a netgroup. 390The third case is specified by the flag 391.Sm off 392.Fl network Li = Sy netname Op Li / Ar prefixlength 393.Sm on 394and optionally 395.Sm off 396.Fl mask No = Sy netmask . 397.Sm on 398The netmask may be specified either by attaching a 399.Ar prefixlength 400to the 401.Fl network 402option, or by using a separate 403.Fl mask 404option. 405If the mask is not specified, it will default to the historical mask 406for that network class (A, B, or C; see 407.Xr inet 4 ) . 408This usage is deprecated, and will elicit a warning log message. 409See the 410.Sx EXAMPLES 411section below. 412.Pp 413Scoped IPv6 address must carry scope identifier as documented in 414.Xr inet6 4 . 415For example, 416.Dq Li fe80::%re2/10 417is used to specify 418.Li fe80::/10 419on 420.Li re2 421interface. 422.Pp 423For the third form which specifies the NFSv4 tree root, the directory path 424specifies the location within the server's file system tree which is the 425root of the NFSv4 tree. 426There can only be one NFSv4 root directory per server. 427As such, all entries of this form must specify the same directory path. 428For file systems other than ZFS, 429this location can be any directory and does not 430need to be within an exported file system. 431If it is not in an exported file system, a very limited set of operations 432are permitted, so that an NFSv4 client can traverse the tree to an 433exported file system. 434Although parts of the NFSv4 tree can be non-exported, the entire NFSv4 tree 435must consist of local file systems capable of being exported via NFS. 436All ZFS file systems in the subtree below the NFSv4 tree root must be 437exported. 438NFSv4 does not use the mount protocol and does permit clients to cross server 439mount point boundaries, although not all clients are capable of crossing the 440mount points. 441.Pp 442The 443.Fl sec 444option on these line(s) specifies what security flavors may be used for 445NFSv4 operations that do not use file handles. 446Since these operations (SetClientID, SetClientIDConfirm, Renew, DelegPurge 447and ReleaseLockOnwer) allocate/modify state in the server, it is possible 448to restrict some clients to the use of the krb5[ip] security flavors, 449via this option. 450See the 451.Sx EXAMPLES 452section below. 453This third form is meaningless for NFSv2 and NFSv3 and is ignored for them. 454.Pp 455The 456.Xr mountd 8 457utility can be made to re-read the 458.Nm 459file by sending it a hangup signal as follows: 460.Bd -literal -offset indent 461service mountd reload 462.Ed 463.Pp 464After sending the 465.Dv SIGHUP , 466check the 467.Xr syslogd 8 468output to see whether 469.Xr mountd 8 470logged any parsing errors in the 471.Nm 472file. 473.Sh FILES 474.Bl -tag -width /etc/exports -compact 475.It Pa /etc/exports 476the default remote mount-point file 477.El 478.Sh EXAMPLES 479Given that 480.Pa /usr , /u , /a 481and 482.Pa /u2 483are 484local file system mount points, let's consider the following example: 485.Pp 486.Bd -literal -offset indent 487/usr /usr/local -maproot=0:10 friends 488/usr -maproot=daemon grumpy.cis.uoguelph.ca 131.104.48.16 489/usr -ro -mapall=nobody 490/u -maproot=bin: -network 131.104.48 -mask 255.255.255.0 491/a -network 192.168.0/24 492/a -network 3ffe:1ce1:1:fe80::/64 493/u2 -maproot=root friends 494/u2 -alldirs -network cis-net -mask cis-mask 495/cdrom -alldirs,quiet,ro -network 192.168.33.0 -mask 255.255.255.0 496/private -sec=krb5i 497/secret -sec=krb5p 498V4: / -sec=krb5:krb5i:krb5p -network 131.104.48 -mask 255.255.255.0 499V4: / -sec=sys:krb5:krb5i:krb5p grumpy.cis.uoguelph.ca 500.Ed 501.Pp 502The file systems rooted at 503.Pa /usr 504and 505.Pa /usr/local 506are exported to hosts within the 507.Dq friends 508network group 509with users mapped to their remote credentials and 510root mapped to UID 0 and group 10. 511They are exported read-write and the hosts in 512.Dq friends . 513.Pp 514The file system rooted at 515.Pa /usr 516is exported to 517.Em 131.104.48.16 518and 519.Em grumpy.cis.uoguelph.ca 520with users mapped to their remote credentials and 521root mapped to the user and groups associated with 522.Dq daemon ; 523it is exported to the rest of the world as read-only with 524all users mapped to the user and groups associated with 525.Dq nobody . 526.Pp 527The file system rooted at 528.Pa /u 529is exported to all hosts on the subnetwork 530.Em 131.104.48 531with root mapped to the UID for 532.Dq bin 533and with no group access. 534.Pp 535The file system rooted at 536.Pa /u2 537is exported to the hosts in 538.Dq friends 539with root mapped to UID and groups 540associated with 541.Dq root ; 542it is exported to all hosts on network 543.Dq cis-net 544allowing mounts at any 545directory within /u2. 546.Pp 547The file system rooted at 548.Pa /a 549is exported to the network 192.168.0.0, with a netmask of 255.255.255.0. 550However, the netmask length in the entry for 551.Pa /a 552is not specified through a 553.Fl mask 554option, but through the 555.Li / Ns Ar prefix 556notation. 557.Pp 558The file system rooted at 559.Pa /a 560is also exported to the IPv6 network 561.Li 3ffe:1ce1:1:fe80:: 562address, using the upper 64 bits as the prefix. 563Note that, unlike with IPv4 network addresses, the specified network 564address must be complete, and not just contain the upper bits. 565With IPv6 addresses, the 566.Fl mask 567option must not be used. 568.Pp 569The file system rooted at 570.Pa /cdrom 571will be exported read-only to the entire network 192.168.33.0/24, including 572all its subdirectories. 573Since 574.Pa /cdrom 575is the conventional mountpoint for a CD-ROM device, 576for the case where the 577.Fl a 578option has been specified for 579.Xr mountd 8 , 580this export will 581fail if no CD-ROM medium is currently mounted there 582since that line 583would then attempt to export a subdirectory of the root file system 584with the 585.Fl alldirs 586option. 587The 588.Fl quiet 589option will then suppress the error message for this condition that 590would normally be syslogged. 591As soon as an actual CD-ROM is going to be mounted, 592.Xr mount 8 593will notify 594.Xr mountd 8 595about this situation, and the 596.Pa /cdrom 597file system will be exported as intended. 598Note that without using the 599.Fl alldirs 600option, the export would always succeed. 601While there is no CD-ROM medium mounted under 602.Pa /cdrom , 603it would export the (normally empty) directory 604.Pa /cdrom 605of the root file system instead. 606.Pp 607The file system rooted at 608.Pa /private 609will be exported using Kerberos 5 authentication and will require 610integrity protected messages for all accesses. 611The file system rooted at 612.Pa /secret 613will also be exported using Kerberos 5 authentication and all messages 614used to access it will be encrypted. 615.Pp 616For the experimental server, the NFSv4 tree is rooted at ``/'', 617and any client within the 131.104.48 subnet is permitted to perform NFSv4 state 618operations on the server, so long as valid Kerberos credentials are provided. 619The machine grumpy.cis.uoguelph.ca is permitted to perform NFSv4 state 620operations on the server using AUTH_SYS credentials, as well as Kerberos ones. 621.Pp 622In the following example some directories are exported as NFSv3 and NFSv4: 623.Bd -literal -offset indent 624V4: /wingsdl/nfsv4 625/wingsdl/nfsv4/usr-ports -maproot=root -network 172.16.0.0 -mask 255.255.0.0 626/wingsdl/nfsv4/clasper -maproot=root clasper 627.Ed 628.Pp 629Only one V4: line is needed or allowed to declare where NFSv4 is 630rooted. 631The other lines declare specific exported directories with 632their absolute paths given in /etc/exports. 633.Pp 634The exported directories' paths are used for both v3 and v4. 635However, they are interpreted differently for v3 and v4. 636A client mount command for usr-ports would use the server-absolute name when 637using nfsv3: 638.Bd -literal -offset indent 639mount server:/wingsdl/nfsv4/usr-ports /mnt/tmp 640.Ed 641.Pp 642A mount command using NFSv4 would use the path relative to the NFSv4 643root: 644.Bd -literal -offset indent 645mount server:/usr-ports /mnt/tmp 646.Ed 647.Pp 648This also differentiates which version you want if the client can do 649both v3 and v4. 650The former will only ever do a v3 mount and the latter will only ever 651do a v4 mount. 652.Pp 653Note that due to different mount behavior between NFSv3 and NFSv4 a 654NFSv4 mount request for a directory that the client does not have 655permission for will succeed and read/write access will fail 656afterwards, whereas NFSv3 rejects the mount request. 657.Sh SEE ALSO 658.Xr vis 1 , 659.Xr strunvis 3 , 660.Xr nfsv4 4 , 661.Xr netgroup 5 , 662.Xr zfsprops 7 , 663.Xr mountd 8 , 664.Xr nfsd 8 , 665.Xr rpc.tlsservd 8 , 666.Xr service 8 , 667.Xr showmount 8 668.Sh STANDARDS 669The implementation is based on the following documents: 670.Bl -dash 671.It 672.Rs 673.%T "Network File System Protocol Specification, Appendix A, RFC 1094" 674.Re 675.It 676.Rs 677.%T "NFS: Network File System Version 3, Appendix I, RFC 1813" 678.Re 679.It 680.Rs 681.%T "Towards Remote Procedure Call Encryption by Default, RFC 9289" 682.Re 683.El 684.Sh BUGS 685The export options are tied to the local mount points in the kernel and 686must be non-contradictory for any exported subdirectory of the local 687server mount point. 688It is recommended that all exported directories within the same server 689file system be specified on adjacent lines going down the tree. 690You cannot specify a hostname that is also the name of a netgroup. 691Specifying the full domain specification for a hostname can normally 692circumvent the problem. 693