diff options
Diffstat (limited to 'usr.sbin/mountd/exports.5')
| -rw-r--r-- | usr.sbin/mountd/exports.5 | 150 |
1 files changed, 117 insertions, 33 deletions
diff --git a/usr.sbin/mountd/exports.5 b/usr.sbin/mountd/exports.5 index d5aa49a1f428..786411fbf6d8 100644 --- a/usr.sbin/mountd/exports.5 +++ b/usr.sbin/mountd/exports.5 @@ -25,10 +25,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" @(#)exports.5 8.3 (Berkeley) 3/29/95 -.\" $FreeBSD$ -.\" -.Dd November 9, 2021 +.Dd August 24, 2025 .Dt EXPORTS 5 .Os .Sh NAME @@ -58,8 +55,8 @@ file system or the NFSv4 tree root for one or more hosts. A long line may be split over several lines by ending all but the last line with a backslash .Pq Ql \e . -A host may be specified only once for each local file or the NFSv4 tree root on the -server and there may be only one default entry for each server +A host may be specified only once for each local file system or the NFSv4 tree +root on the server and there may be only one default entry for each server file system that applies to all other hosts. The latter exports the file system to the .Dq world @@ -69,7 +66,35 @@ be used only when the file system contains public information. In a mount entry, the first field(s) specify the directory path(s) within a server file system that can be mounted on by the corresponding client(s). -There are three forms of this specification. +Note well that exporting a directory on the server does not guarantee that only +files below the exported directory will be accessible. +This is true even in the absence of the +.Fl alldirs +flag. +To provide this guarantee, the exported directories must be local file system +mount points on the server. +For example, if one exports +.Pa /home , +and +.Pa /home +is not a file system mount point, then clients will be able to access arbitrary +files on the root file system. +As such, to avoid confusion with respect to what is exported, it may be prudent +to limit exported directories to server local file system mount points. +When exporting ZFS datasets with the +.Sy sharenfs +property, this is auomatically the case. +If the +.Fl alldirs +flag is specified and +the +.Fl a +command line option is specified for +.Xr mountd 8 , +the export will fail if the directory path is not a local file system +mount point. +.Pp +There are three forms of the directory path specification. The first is to list all mount points as absolute directory paths separated by whitespace. This list of directory paths should be considered an @@ -109,9 +134,33 @@ any or .Dq Pa .. components. +Pathnames are decoded by +.Xr strunvis 3 +allowing special characters to be included in the directory name(s). +In particular, whitespace, such as embedded blanks in directory names +can be handled. +For example, a blank can be encoded as \(rs040. +.Xr vis 1 +with the +.Fl M +option may be used to encode directory name(s) with embedded special +characters. Mount points for a file system may appear on multiple lines each with different sets of hosts and export options. .Pp +Note that, for NFSv4 exporting, there must be both one or more ``V4:'' line(s) +and one or more line(s) exporting the file systems that are to be +exported to NFSv4 clients. +If there are multiple ``V4:'' lines, these lines must all specify the +same root directory path, but with different options for different +clients. +These line(s) do not export any file system, but simply define the +location of the ``root'' of the NFSv4 export subtree. +The line(s) exporting the file systems should always +specify the pathname of the root of a server file system +and must include at least one line exporting the file system +which is specified as the ``root'' by the ``V4:'' line(s). +.Pp The second component of a line specifies how the file system is to be exported to the host set. The option flags specify whether the file system @@ -143,8 +192,23 @@ The user string may be quoted, or use backslash escaping. 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. +Note that +.Cm user: +should be used to specify a credential containing no groups, in which case the +established credential will use +.Ql nogroup , +else 65533 +.Pq Dv GID_NOGROUP , +as the fallback group +.Pq a credential object must have at least one group internally . +Using just +.Cm user +.Pq without colon at end +falls into the +.Sm off +.Fl maproot Li = Sy user +.Sm on +case described above. The group names may be quoted, or use backslash escaping. .Pp .Sm off @@ -251,7 +315,7 @@ The and .Fl tlscertuser export options are used to require the client to use TLS for the mount(s) -per RFC NNNN. +per RFC 9289. For NFS mounts using TLS to work, .Xr rpc.tlsservd 8 must be running on the server. @@ -394,7 +458,7 @@ utility can be made to re-read the .Nm file by sending it a hangup signal as follows: .Bd -literal -offset indent -/etc/rc.d/mountd reload +service mountd reload .Ed .Pp After sending the @@ -412,6 +476,13 @@ file. the default remote mount-point file .El .Sh EXAMPLES +Given that +.Pa /usr , /u , /a +and +.Pa /u2 +are +local file system mount points, let's consider the following example: +.Pp .Bd -literal -offset indent /usr /usr/local -maproot=0:10 friends /usr -maproot=daemon grumpy.cis.uoguelph.ca 131.104.48.16 @@ -428,27 +499,21 @@ V4: / -sec=krb5:krb5i:krb5p -network 131.104.48 -mask 255.255.255.0 V4: / -sec=sys:krb5:krb5i:krb5p grumpy.cis.uoguelph.ca .Ed .Pp -Given that -.Pa /usr , /u , /a -and -.Pa /u2 -are -local file system mount points, the above example specifies the following: -.Pp -The file system rooted at +The file systems rooted at .Pa /usr -is exported to hosts -.Em friends -where friends is specified in the netgroup file +and +.Pa /usr/local +are exported to hosts within the +.Dq friends +network group 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 -.Dq friends -can mount either +They are exported read-write and the hosts in +.Dq friends . +.Pp +The file system rooted at .Pa /usr -or -.Pa /usr/local . -It is exported to +is exported to .Em 131.104.48.16 and .Em grumpy.cis.uoguelph.ca @@ -507,12 +572,18 @@ will be exported read-only to the entire network 192.168.33.0/24, including all its subdirectories. Since .Pa /cdrom -is the conventional mountpoint for a CD-ROM device, this export will -fail if no CD-ROM medium is currently mounted there since that line +is the conventional mountpoint for a CD-ROM device, +for the case where the +.Fl a +option has been specified for +.Xr mountd 8 , +this export will +fail if no CD-ROM medium is currently mounted there +since that line would then attempt to export a subdirectory of the root file system with the .Fl alldirs -option which is not allowed. +option. The .Fl quiet option will then suppress the error message for this condition that @@ -584,19 +655,32 @@ NFSv4 mount request for a directory that the client does not have permission for will succeed and read/write access will fail afterwards, whereas NFSv3 rejects the mount request. .Sh SEE ALSO +.Xr vis 1 , +.Xr strunvis 3 , .Xr nfsv4 4 , .Xr netgroup 5 , +.Xr zfsprops 7 , .Xr mountd 8 , .Xr nfsd 8 , .Xr rpc.tlsservd 8 , +.Xr service 8 , .Xr showmount 8 .Sh STANDARDS -The implementation is based on the specification in +The implementation is based on the following documents: +.Bl -dash +.It .Rs .%T "Network File System Protocol Specification, Appendix A, RFC 1094" +.Re +.It +.Rs .%T "NFS: Network File System Version 3, Appendix I, RFC 1813" -.%T "Towards Remote Procedure Call Encryption By Default, RFC nnnn" .Re +.It +.Rs +.%T "Towards Remote Procedure Call Encryption by Default, RFC 9289" +.Re +.El .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 |