usr.sbin/mountd/exports.5

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