489 lines
14 KiB
Groff
489 lines
14 KiB
Groff
.\" $NetBSD: exports.5,v 1.39 2024/03/29 22:50:27 uwe Exp $
|
|
.\"
|
|
.\" Copyright (c) 1989, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)exports.5 8.3 (Berkeley) 3/29/95
|
|
.\"
|
|
.Dd March 27, 2024
|
|
.Dt EXPORTS 5
|
|
.Os
|
|
.Sh NAME
|
|
.Nm exports
|
|
.Nd exported filesystem mount points for
|
|
.Tn NFS
|
|
mount requests
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
file on an
|
|
.Tn NFS
|
|
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
|
|
.D1 Li / Ns Ar dir Li ... Oo Ar host | Ar netgroup | Fl Ar option Oc Li ...
|
|
.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
|
|
contents of the filesystem that the directory lives in to
|
|
.Tn NFS
|
|
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
|
|
.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
|
|
.Po see
|
|
.Xr netgroup 5
|
|
.Pc
|
|
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
|
|
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
|
|
.It Fl alldirs
|
|
Allow mount requests from clients at any point within the filesystem,
|
|
including regular files.
|
|
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.
|
|
.Sm off
|
|
.It Fl maproot Li = 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
|
|
.Po see
|
|
.Xr id 1
|
|
.Pc .
|
|
The user may be specified by name or number.
|
|
.Sm off
|
|
.It Fl maproot Li = Ar user\^ Li \&: Op Ar group1\^ Li \&: group2\^ Li \&: Ar ...
|
|
.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
|
|
.Sq Ar user\^ Ns Li \&:
|
|
(with the trailing colon)
|
|
should be used to distinguish a credential containing no groups from a
|
|
complete credential for that user.
|
|
.Sm off
|
|
.It Fl mapall Li = Ar user
|
|
.It Fl mapall Li = Ar user\^ Li \&: Op Ar group1\^ Li \&: Ar group2\^ Li \&: Ar ...
|
|
.Sm on
|
|
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 Li \&: Ns Op Ar group1\^ Ns Li \&: Ns Ar group2\^ Ns Li \&: Ns Ar ...
|
|
Synonym for
|
|
.Fl maproot ,
|
|
for compatibility with older export file formats.
|
|
.Pp
|
|
.Em Note :
|
|
Not a synonym for the read-only option
|
|
.Fl ro .
|
|
.El
|
|
.Pp
|
|
In the absence of
|
|
.Fl maproot
|
|
and
|
|
.Fl mapall
|
|
options, remote accesses by root will result in using a credential of -2:-2.
|
|
All other users will be mapped to their remote credential.
|
|
If a
|
|
.Fl maproot
|
|
option is given,
|
|
remote access by root will be mapped to that credential instead of -2:-2.
|
|
If a
|
|
.Fl mapall
|
|
option is given,
|
|
all users (including root) will be mapped to that credential in
|
|
place of their own.
|
|
.Bl -tag -width Fl
|
|
.It Fl kerb
|
|
Specifies that the Kerberos authentication server should be
|
|
used to authenticate and map client credentials.
|
|
.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
|
|
.Po
|
|
except for named pipes, sockets, and device nodes, where
|
|
write semantics is client-side anyway
|
|
.Pc .
|
|
.It Fl o
|
|
Synonym for
|
|
.Fl ro
|
|
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.
|
|
.\" 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 ,
|
|
.Fl mapall=nobody ,
|
|
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
|
|
.Pq Fl noresvport , Fl noresvmnt
|
|
.It
|
|
not remapping uids
|
|
.El
|
|
.Pp
|
|
.Bf -symbolic
|
|
Warning:
|
|
.Fl public
|
|
is only provided to conform to the spec, and should normally
|
|
not be used.
|
|
.Ef
|
|
For a WebNFS export,
|
|
use the
|
|
.Fl webnfs
|
|
flag.
|
|
.It Fl index Ns Li = Ns Ar file
|
|
(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
|
|
.Fl public
|
|
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
|
|
.Sm off
|
|
.It Fl network Li = Ar netname Op Li / Ar prefixlength
|
|
.Sm on
|
|
Export the filesystem to all hosts in the specified network.
|
|
.Pp
|
|
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 netmask may be specified either by
|
|
.Ar prefixlength ,
|
|
or
|
|
.Pq 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
|
|
class
|
|
.Po
|
|
A, B or C; see
|
|
.Xr inet 4
|
|
.Pc .
|
|
.Pp
|
|
Scoped IPv6 address must carry a scope identifier as documented in
|
|
.Xr inet6 4 .
|
|
For example,
|
|
.Ql fe80::%ne2/10
|
|
is used to specify
|
|
.Ql fe80::/10
|
|
on
|
|
.Ql 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 Pa -compact
|
|
.It Pa /etc/exports
|
|
The default remote mount-point file.
|
|
.El
|
|
.Pp
|
|
If you have modified the
|
|
.Pa /etc/exports
|
|
file, send the mountd process a
|
|
.Dv SIGHUP
|
|
to make it re-read it:
|
|
.Pp
|
|
.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
|
|
/usr -ro -mapall=nobody
|
|
/u -maproot=bin: -network 131.104.48 -mask 255.255.255.0
|
|
/a -network 192.168.0/24
|
|
/a -network 3ffe:1ce1:1:fe80::/64
|
|
/u2 -maproot=root friends
|
|
/u2 -alldirs -kerb -network cis-net -mask cis-mask
|
|
.Ed
|
|
.Pp
|
|
Given that
|
|
.Pa /usr ,
|
|
.Pa /u ,
|
|
and
|
|
.Pa /u2
|
|
are local filesystem mount points, the above example specifies the
|
|
following:
|
|
.Bl -tag -width ".Pa /usr"
|
|
.It Pa /usr
|
|
is exported to hosts
|
|
.Ql friends
|
|
where
|
|
.Ql friends
|
|
is specified in the
|
|
.Xr netgroup 5
|
|
file with users mapped to their remote credentials and
|
|
root mapped to uid 0 and group 10.
|
|
It is exported read-write and the hosts in
|
|
.Ql friends
|
|
can mount either
|
|
.Pa /usr
|
|
or
|
|
.Pa /usr/local .
|
|
.Pp
|
|
It is also exported to
|
|
.Ql 131.104.48.16
|
|
and
|
|
.Ql grumpy.cis.uoguelph.ca
|
|
with users mapped to their remote credentials and
|
|
root mapped to the user and groups associated with
|
|
.Ql 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
|
|
.Ql nobody .
|
|
.It Pa /u
|
|
is exported to all hosts on the subnetwork
|
|
.Ql 131.104.48
|
|
with root mapped to the uid for
|
|
.Ql bin
|
|
and with no group access.
|
|
.It Pa /u2
|
|
is exported to the hosts in
|
|
.Ql friends
|
|
with root mapped to uid and groups associated with
|
|
.Ql root ;
|
|
it is exported to all hosts on network
|
|
.Ql cis-net
|
|
allowing mounts at any
|
|
directory within
|
|
.Pa /u2
|
|
and mapping all uids to credentials for the principal
|
|
that is authenticated by a Kerberos ticket.
|
|
.Pq Sy Kerberos not implemented.
|
|
.It Pa /a
|
|
is exported to the network
|
|
.Ql 192.168.0.0 ,
|
|
with a netmask of
|
|
.Ql 255.255.255.0 .
|
|
However, the netmask in the entry for
|
|
.Pa /a
|
|
is not specified through a
|
|
.Fl mask
|
|
option, but through the
|
|
.Li / Ns Ar prefixlen
|
|
notation.
|
|
.It Pa /a
|
|
is also exported to the IPv6 network
|
|
.Ql 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
|
|
.Fl mask
|
|
option must not be used.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr netgroup 5 ,
|
|
.Xr mountd 8 ,
|
|
.Xr nfsd 8 ,
|
|
.Xr showmount 8
|
|
.Rs
|
|
.%T NFS: Network File System Protocol Specification
|
|
.%R RFC 1094
|
|
.%I IETF Network Working Group
|
|
.%O Appendix A
|
|
.%U https://datatracker.ietf.org/doc/html/rfc1094#appendix-A.1
|
|
.Re
|
|
.Rs
|
|
.%A B. Callaghan
|
|
.%A B. Pawlowski
|
|
.%A P. Staubach
|
|
.%T NFS Version 3 Protocol Specification
|
|
.%R RFC 1813
|
|
.%I IETF Network Working Group
|
|
.%O Appendix I
|
|
.%U https://datatracker.ietf.org/doc/html/rfc1813#section-5.0
|
|
.Re
|
|
.Sh CAVEATS
|
|
Don't re-export NFS-mounted filesystems unless you are sure of the
|
|
implications.
|
|
NFS has some assumptions about the characteristics of the file
|
|
systems being exported, e.g. when timestamps are updated.
|
|
Re-exporting should work to some extent and can even be useful in
|
|
some cases, but don't expect it works as well as with local file
|
|
systems.
|
|
.Pp
|
|
Filesystems that provide a namespace for a subtree of another
|
|
filesystem such as nullfs
|
|
.Pq Xr mount_null 8
|
|
and umapfs
|
|
.Pq Xr mount_umap 8
|
|
.Em do not
|
|
restrict
|
|
.Tn NFS
|
|
clients to that namespace, so they cannot be used to securely limit
|
|
.Tn NFS
|
|
clients to a subtree of a filesystem.
|
|
If you want to export one subtree and prevent access to other subtrees,
|
|
the exported subtree must be on its own filesystem on the server.
|
|
.Sh BUGS
|
|
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.
|
|
Specifying the full domain specification for a hostname can normally
|
|
circumvent the problem.
|