Module Name: src
Committed By: riastradh
Date: Wed Mar 27 01:43:26 UTC 2024
Modified Files:
src/usr.sbin/mountd: exports.5
Log Message:
exports(5): Substantially rewrite for clarity.
Hope this is an improvement over the turgid paragraphs all about
first/second/third cases of everything.
PR misc/58063
To generate a diff of this commit:
cvs rdiff -u -r1.34 -r1.35 src/usr.sbin/mountd/exports.5
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/usr.sbin/mountd/exports.5
diff -u src/usr.sbin/mountd/exports.5:1.34 src/usr.sbin/mountd/exports.5:1.35
--- src/usr.sbin/mountd/exports.5:1.34 Wed Mar 27 00:46:17 2024
+++ src/usr.sbin/mountd/exports.5 Wed Mar 27 01:43:26 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: exports.5,v 1.34 2024/03/27 00:46:17 riastradh Exp $
+.\" $NetBSD: exports.5,v 1.35 2024/03/27 01:43:26 riastradh Exp $
.\"
.\" Copyright (c) 1989, 1991, 1993
.\" The Regents of the University of California. All rights reserved.
@@ -39,116 +39,147 @@
mount requests
.Sh DESCRIPTION
The
-.Nm exports
+.Nm
file on an
.Tn NFS
-server, used by
-.Xr mountd 8 ,
-lists filesystems to be exported to
+server lists filesystems to be exported to
.Tn NFS
clients.
+It is read and applied by
+.Xr mountd 8
+on start and on
+.Dv SIGHUP .
+.Pp
+Each entry in
+.Nm
+is a line with a list of directories followed by a list of hosts,
+netgroups, and options, separated by spaces or tabs:
+.Pp
+.Dl Pf / Va dir "..." Oo Va host | Va netgroup | Fl Va option Oc "..."
+.Pp
+All directories in a single line must live in the same filesystem,
+which is exported to the hosts and netgroups listed, according to the
+options specified.
+Exported directories must not have pathname components that are
+symbolic links,
+.Ql "." ,
+or
+.Ql ".." .
.Pp
+.Bf -symbolic
+Warning:
Exporting a directory exposes the
.Em entire
content of the filesystem that the directory lives in to
.Tn NFS
-clients, even it it isn't the root directory of a filesystem on the
-server.
-The list of exports is only what the server advertises to clients in
-the mount protocol, not a restriction on what files or directories
-within exported filesystems clients have access to with
-.Tn NFS .
-.Pp
-Each line in the file
-(other than comment lines that begin with a
-.Sq # )
-specifies the mount point(s) and export flags within one local server
-filesystem for one or more hosts.
-A host may be specified only once for each local filesystem on the
-server and there may be only one default entry for each server
-filesystem that applies to all other hosts.
-The latter exports the filesystem to the
-.Dq world
-and should
-be used only when the filesystem contains public information.
+clients.
+.Ef
+This happens even if an exported directory is not the root directory of
+a filesystem on the server.
+.Tn NFS
+clients are only prevented from access to files and directories on
+filesystems that are
+.Em not
+exported at all.
.Pp
-If you have modified the
-.Pa /etc/exports
-file, send the mountd a SIGHUP to make it re-read the
-.Pa /etc/exports
-file:
-.Dq kill -HUP `cat /var/run/mountd.pid` .
+.Bf -symbolic
+Warning:
+Access control is only by network address.
+.Ef
+.Tn NFS
+servers with any non-public data should be exposed only to restricted
+or firewalled networks with ingress filtering.
+There is no authentication or encryption to make it safe for
+restricting access on the open internet.
+.Pp
+Blank lines are ignored.
+Text beginning with
+.Ql #
+until the end of line is ignored as a comment.
+Each line ending with
+.Ql \e
+has the next line appended, without the
+.Ql \e ,
+as a continuation line.
+Characters can be escaped with
+.Ql \e .
+.Pp
+All directories, which begin with
+.Ql / ,
+must come before any hosts, netgroups, or options on a line.
+Options begin with
+.Ql - .
+All other items on an export line are interpreted either as netgroups
+(see
+.Xr netgroup 5 )
+or as hosts, which can be either names, as in example.com, or numbers,
+as in 192.0.2.123 or 2001:db8:1234:abcd::42.
+Sets of hosts in a contiguous network range can be specified with the
+.Fl network
+option.
.Pp
-In a mount entry,
-the first field(s) specify the directory path(s) within a server filesystem
-that can be mounted on by the corresponding client(s).
-There are two forms of this specification.
-The first is to list all mount points as absolute
-directory paths separated by whitespace.
-The second is to specify the pathname of the root of the filesystem
-followed by the
-.Fl alldirs
-flag;
-this form allows the host(s) to mount at any point within the filesystem,
+The same filesystem may be exported on multiple lines with different
+options to different sets of hosts, as long as it is exported at most
+once to each host, netgroup, or network.
+.Pp
+Export lines with no hosts, netgroups, or
+.Fl network
+options are exported to
+.Em any
+hosts on the network, with no access control.
+.Pp
+Supported export options:
+.Bl -tag -width ".Fl noresvport"
+.It Fl alldirs
+Allow mount requests from clients at any point within the filesystem,
including regular files.
-Note that the
+Only the root directory of the filesystem should be specified on the
+line.
+.Pp
+Note that omitting the
.Fl alldirs
option should not be used as a security measure to make clients mount
only those subdirectories that they should have access to.
A client
can still access the whole filesystem via individual RPCs if it
wanted to, even if just one subdirectory has been mounted.
-The pathnames must not have any symbolic links in them and should not have
-any
-.Dq \&.
-or
-.Dq ..
-components.
-Mount points for a filesystem may appear on multiple lines each with
-different sets of hosts and export options.
-.Pp
-The second component of a line specifies how the filesystem is to be
-exported to the host set.
-The option flags specify whether the filesystem
-is exported read-only or read-write and how the client uid is mapped to
-user credentials on the server.
-.Pp
-Export options are specified as follows:
-.Pp
.Sm off
-.Fl maproot No = Ar user
+.It Fl maproot No = Ar user
.Sm on
The credential of the specified user is used for remote access by root.
The credential includes all the groups to which the user is a member
on the local machine (see
.Xr id 1 ) .
The user may be specified by name or number.
-.Pp
.Sm off
-.Fl maproot No = Ar user : group1 : group2 : ...
+.It Fl maproot No = Ar user : group1 : group2 : ...
.Sm on
The colon separated list is used to specify the precise credential
to be used for remote access by root.
The elements of the list may be either names or numbers.
-Note that user: should be used to distinguish a credential containing
-no groups from a complete credential for that user.
-.Pp
+Note that
.Sm off
-.Fl mapall No = Ar user
+.Ql Ar user ":"
.Sm on
-or
+should be used to distinguish a credential containing no groups from a
+complete credential for that user.
.Sm off
-.Fl mapall No = Ar user : group1 : group2 : ...
+.It Fl mapall No = Ar user
+.It Fl mapall No = Ar user : group1 : group2 : ...
.Sm on
-specifies a mapping for all client uids (including root)
+Mapping for all client uids (including root)
using the same semantics as
.Fl maproot .
+.It Fl r Ar user
+.It Fl r Ar user Ns : Ns Ar group1 Ns : Ns Ar group2 Ns : Ar ...
+Synonym for
+.Fl maproot ,
+for compatibility with older export file formats.
.Pp
-The option
-.Fl r
-is a synonym for
-.Fl maproot
-in an effort to be backward compatible with older export file formats.
+Note:
+Not a synonym for the read-only option
+.Fl ro .
+.El
.Pp
In the absence of
.Fl maproot
@@ -165,66 +196,83 @@ If a
option is given,
all users (including root) will be mapped to that credential in
place of their own.
-.Pp
-The
-.Fl kerb
-option specifies that the Kerberos authentication server should be
+.Bl -tag -width ".Fl noresvport"
+.It Fl kerb
+Specifies that the Kerberos authentication server should be
used to authenticate and map client credentials.
-This option is currently not implemented.
-.Pp
-The
-.Fl ro
-option specifies that the filesystem should be exported read-only
-(default read/write).
-The option
-.Fl o
-is a synonym for
+.Sy This option is currently not implemented.
+.It Fl ro
+Export filesystem read-only.
+Clients will be forbidden to change or write to anything in the
+filesystem (except for named pipes, sockets, and device nodes, where
+write semantics is client-side anyway).
+.It Fl o
+Synonym for
.Fl ro
-in an effort to be backward compatible with older export file formats.
-.Pp
-The
-.Fl noresvport
-option specifies that NFS RPC calls for the filesystem do not have to come
-from reserved ports.
+for compatibility with older export file formats.
+.It Fl noresvport
+Allow NFS RPC calls for the filesystem to come from non-reserved
+ports.
Normally, clients are required to use reserved ports for operations.
Using this option decreases the security of your system.
-.Pp
-The
-.Fl noresvmnt
-option specifies that mount RPC requests for the filesystem do not have
-to come from reserved ports.
+.\" XXX ^ Not really...
+.It Fl noresvmnt
+Allow mount RPC requests for the filesystem to come from non-reserved
+ports.
Normally, clients are required to use reserved ports for mount requests.
Using this option decreases the security of your system.
+.\" XXX ^ Not really...
+.It Fl webnfs
+(WebNFS)
+Enables WebNFS export, equivalent to combining
+.Fl public ,
+.Sm off
+.Fl mapall No = Ar nobody ,
+.Sm on
+and
+.Fl ro .
+.It Fl public
+(WebNFS)
+Enables WebNFS export strictly according to the spec,
+RFC 2054 and RFC 2055.
+This implies:
+.Bl -bullet -compact
+.It
+read/write access to all files in the filesystem
+.It
+not requiring reserved ports
+.Pf ( Fl noresvport , Fl noresvmnt )
+.It
+not remapping uids
+.El
.Pp
-WebNFS exports strictly according to the spec (RFC 2054 and RFC 2055) can
-be done with the
+.Bf -symbolic
+Warning:
.Fl public
-flag.
-However, this flag in itself allows r/w access to all files in
-the filesystem, not requiring reserved ports and not remapping uids.
-It is only provided to conform to the spec, and should normally
+is only provided to conform to the spec, and should normally
not be used.
+.Ef
For a WebNFS export,
use the
.Fl webnfs
flag, which implies
.Fl public ,
.Sm off
-.Fl mapall No = Ar nobody
+.Fl mapall No = Ar nobody ,
.Sm on
and
.Fl ro .
-.Pp
-A
.Sm off
-.Fl index No = Ar file
+.It Fl index No = Ar file
.Sm on
-option can be used to specify a file whose handle will be returned if
-a directory is looked up using the public filehandle (WebNFS).
+(WebNFS)
+File whose handle will be returned if
+a directory is looked up using the public filehandle.
This is to mimic the behavior of URLs.
If no
.Fl index
option is specified, a directory filehandle will be returned as usual.
+.Pp
The
.Fl index
option only makes sense in combination with the
@@ -232,57 +280,32 @@ option only makes sense in combination w
or
.Fl webnfs
flags.
+.El
.Pp
.Bf -symbolic
Warning: exporting a filesystem both using WebNFS and read/write in
the normal way to other hosts should be avoided in an environment
that is vulnerable to IP spoofing.
.Ef
+.\" XXX Isn't this an issue for _all_ read/write exports, not just
+.\" WebNFS ones?
WebNFS enables any client to get filehandles to the exported filesystem.
Using IP spoofing, a client could then pretend to be a host to which
the same filesystem was exported read/write, and use the handle to
gain access to that filesystem.
+.Bl -tag -width ".Fl noresvport"
+.Sm off
+.It Fl network No = Ar netname Op No / Ar prefixlength
+.Sm on
+Export the filesystem to all hosts in the specified network.
.Pp
-The third component of a line specifies the host set to which the line applies.
-If no host set is specified, the filesystem is exported to everyone.
-The set may be specified in three ways.
-The first way is to list the host name(s) separated by white space.
-(Standard internet
-.Dq dot
-addresses may be used in place of names.)
-The second way is to specify a
-.Dq netgroup
-as defined in the netgroup file (see
-.Xr netgroup 5 ) .
-A netgroup that contains an item that does have a host entry
-is treated like an error.
-The third way is to specify an internet subnetwork using a network and
-network mask that is defined as the set of all hosts with addresses within
-the subnetwork.
-This latter approach requires less overhead within the
+This approach to identifying hosts requires less overhead within the
kernel and is recommended for cases where the export line refers to a
large number of clients within an administrative subnet.
.Pp
-The first two cases are specified by simply listing the name(s) separated
-by whitespace.
-All names are checked to see if they are
-.Dq netgroup
-names first and are assumed to be hostnames otherwise.
-Using the full domain specification for a hostname can normally
-circumvent the problem of a host that has the same name as a netgroup.
-The third case is specified by the flag
-.Sm off
-.Fl network No = Ar netname Op No / Ar prefixlength
-.Sm on
-and optionally
-.Sm off
-.Fl mask No = Ar netmask .
-.Sm on
-The netmask may be specified either by attaching a
-.Ar prefixlength
-to the
-.Fl network
-option, or by using a separate
+The netmask may be specified either by
+.Ar prefixlength ,
+or (for IPv4 networks only) by using a separate
.Fl mask
option.
If the mask is not specified, it will default to the mask for that network
@@ -294,8 +317,28 @@ Scoped IPv6 address must carry scope ide
For example,
.Dq fe80::%ne2/10
is used to specify fe80::/10 on ne2 interface.
+.Sm off
+.It Fl mask No = Ar netmask .
+.Sm on
+(IPv4-only)
+Netmask for
+.Fl network
+options with no
+.Ar prefixlength .
+.El
+.Sh FILES
+.Bl -tag -width /etc/exports -compact
+.It Pa /etc/exports
+The default remote mount-point file.
+.El
.Pp
-For example:
+If you have modified the
+.Pa /etc/exports
+file, send the mountd a SIGHUP to make it re-read the
+.Pa /etc/exports
+file:
+.Dl "kill -HUP $(cat /var/run/mountd.pid)" .
+.Sh EXAMPLES
.Bd -literal -offset indent
/usr /usr/local -maproot=0:10 friends
/usr -maproot=daemon grumpy.cis.uoguelph.ca 131.104.48.16
@@ -314,7 +357,8 @@ and
.Pa /u2
are local filesystem mount points, the above example specifies the
following:
-.Pa /usr
+.Bl -tag -width ".Pa /usr"
+.It Pa /usr
is exported to hosts
.Em friends
where friends is specified in the netgroup file
@@ -326,25 +370,25 @@ can mount either
.Pa /usr
or
.Pa /usr/local .
-It is exported to
+.Pp
+It is also exported to
.Em 131.104.48.16
and
.Em grumpy.cis.uoguelph.ca
with users mapped to their remote credentials and
root mapped to the user and groups associated with
-.Dq daemon ;
-it is exported to the rest of the world as read-only with
+.Dq daemon .
+.Pp
+It is also exported to the rest of the world as read-only with
all users mapped to the user and groups associated with
.Dq nobody .
-.Pp
-.Pa /u
+.It Pa /u
is exported to all hosts on the subnetwork
.Em 131.104.48
with root mapped to the uid for
.Dq bin
and with no group access.
-.Pp
-.Pa /u2
+.It Pa /u2
is exported to the hosts in
.Dq friends
with root mapped to uid and groups associated with
@@ -354,23 +398,24 @@ it is exported to all hosts on network
allowing mounts at any
directory within /u2 and mapping all uids to credentials for the principal
that is authenticated by a Kerberos ticket.
-.Pp
-.Pa /a
+.Sy (Kerberos not implemented.)
+.It Pa /a
is exported to the network 192.168.0.0, with a netmask of 255.255.255.0.
-However, the netmask length in the entry for /a is not specified through
-a -mask option, but through the /prefix notation.
-.Pp
+However, the netmask in the entry for
.Pa /a
+is not specified through a
+.Fl mask
+option, but through the
+.Pf / Ar prefixlen
+notation.
+.It Pa /a
is also exported to the IPv6 network 3ffe:1ce1:1:fe80:: address, using
the upper 64 bits as the prefix.
Note that, unlike with IPv4 network addresses, the specified network
address must be complete, and not just contain the upper bits.
-With IPv6 addresses, the -mask option must not
-be used.
-.Sh FILES
-.Bl -tag -width /etc/exports -compact
-.It Pa /etc/exports
-The default remote mount-point file.
+With IPv6 addresses, the
+.Fl mask
+option must not be used.
.El
.Sh SEE ALSO
.Xr netgroup 5 ,
@@ -421,6 +466,8 @@ the exported subtree must be on its own
The export options are tied to the local mount points in the kernel and
must be non-contradictory for any exported subdirectory of the local
server mount point.
+.\" XXX Explain what `contradictory' means here and give some positive
+.\" and negative examples.
It is recommended that all exported directories within the same server
filesystem be specified on adjacent lines going down the tree.
You cannot specify a hostname that is also the name of a netgroup.
