12278 nfs-zone needs man page changes

Reviewed by: Peter Tribble <peter.tribble@gmail.com>
Reviewed by: Gordon Ross <gordon.w.ross@gmail.com>
Approved by: Joshua M. Clulow <josh@sysmgr.org>

4 files changed, 50 insertions, 36 deletions

diff --git a/usr/src/man/man1m/nfsd.1m b/usr/src/man/man1m/nfsd.1m
index e188fdd29b..82b3282718 100644
--- a/usr/src/man/man1m/nfsd.1m
+++ b/usr/src/man/man1m/nfsd.1m
@@ -18,8 +18,9 @@
 .\" Copyright 1989 AT&T
 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved
 .\" Copyright 2016 Nexenta Systems, Inc.
+.\" Copyright 2020 Joyent, Inc.
 .\"
-.Dd March 12, 2016
+.Dd February 4, 2020
 .Dt NFSD 1M
 .Os
 .Sh NAME
@@ -178,7 +179,8 @@ Daemon failed to start.
 .Xr sharetab 4 ,
 .Xr system 4 ,
 .Xr attributes 5 ,
-.Xr smf 5
+.Xr smf 5 ,
+.Xr zones 5
 .Sh NOTES
 Manually starting and restarting
 .Nm
@@ -193,7 +195,9 @@ unless its
 .Sy application Ns / Ns Sy auto_enable
 property is set to
 .Sy false .
-See the , and
+See
+.Xr smf 5
+and
 .Xr svcadm 1M
 for more information.
 .Pp
@@ -222,3 +226,10 @@ Instead,
 .Nm
 can be restarted by other signals, such as
 .Sy SIGINT .
+.Pp
+NFS service, which includes
+.Nm ,
+can run inside a non-global zone.
+See the discussion under ZONES in
+.Xr nfs 4
+for more information.
diff --git a/usr/src/man/man4/nfs.4 b/usr/src/man/man4/nfs.4
index 56b1fae33c..29b60bf5e2 100644
--- a/usr/src/man/man4/nfs.4
+++ b/usr/src/man/man4/nfs.4
@@ -18,8 +18,9 @@
 .\" Copyright 1989 AT&T
 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
 .\" Copyright 2016 Nexenta Systems, Inc.
+.\" Copyright 2020 Joyent, Inc.
 .\"
-.Dd December 18, 2016
+.Dd February 4, 2020
 .Dt NFS 4
 .Os
 .Sh NAME
@@ -296,6 +297,16 @@ However, this is not functionally different from mapping the inbound string to
 .Sy nobody ,
 yet provides greater flexibility.
 .El
+.Sh ZONES
+NFS can be served out of a non-global zone.
+All of the above documentation applies to an in-zone NFS server.
+File sharing in zones is restricted to filesystems a zone completely controls.
+Some zone brands (see
+.Xr brands 5 )
+do not give the zone's root its own filesystem, for example.
+Delegated ZFS datasets to a zone are shareable, as well as lofs-remounted
+directories.
+The zone must have sys_nfs privileges; most brands grant this already.
 .Sh SEE ALSO
 .Xr lockd 1M ,
 .Xr mount_nfs 1M ,
@@ -303,4 +314,6 @@ yet provides greater flexibility.
 .Xr nfsd 1M ,
 .Xr nfsmapid 1M ,
 .Xr sharectl 1M ,
-.Xr smf 5
+.Xr brands 5 ,
+.Xr smf 5 ,
+.Xr zones 5
diff --git a/usr/src/man/man5/zones.5 b/usr/src/man/man5/zones.5
index d4f03efb76..d860f3b290 100644
--- a/usr/src/man/man5/zones.5
+++ b/usr/src/man/man5/zones.5
@@ -3,12 +3,12 @@
 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
+.\"
+.\" Copyright 2020 Joyent, Inc.
 .TH ZONES 5 "Jan 29, 2009"
 .SH NAME
 zones \- Solaris application containers
 .SH DESCRIPTION
-.sp
-.LP
 The zones facility in Solaris provides an isolated environment for running
 applications. Processes running in a zone are prevented from monitoring or
 interfering with other activity in the system. Access to other processes,
@@ -118,8 +118,6 @@ cannot be destroyed. Such cases require operator intervention.
 .RE
 
 .SS "Process Access Restrictions"
-.sp
-.LP
 Processes running inside a zone (aside from the global zone) have restricted
 access to other processes. Only processes in the same zone are visible through
 \fB/proc\fR (see \fBproc\fR(4) or through system call interfaces that take
@@ -127,8 +125,6 @@ process IDs such as \fBkill\fR(2) and \fBpriocntl\fR(2). Attempts to access
 processes that exist in other zones (including the global zone) fail with the
 same error code that would be issued if the specified process did not exist.
 .SS "Privilege Restrictions"
-.sp
-.LP
 Processes running within a non-global zone are restricted to a subset of
 privileges, in order to prevent one zone from being able to perform operations
 that might affect other zones. The set of privileges limits the capabilities of
@@ -137,8 +133,6 @@ list of privileges available within a zone can be displayed using the
 \fBppriv\fR(1) utility. For more information about privileges, see
 \fBprivileges\fR(5).
 .SS "Device Restrictions"
-.sp
-.LP
 The set of devices available within a zone is restricted, to prevent a process
 in one zone from interfering with processes in other zones. For example, a
 process in a zone should not be able to modify kernel memory using
@@ -153,8 +147,6 @@ that can run in a non-global zone. For example, the \fBeeprom\fR(1M),
 \fBprtdiag\fR(1M), and \fBprtconf\fR(1M) utilities do not work in a zone since
 they rely on devices that are not normally available.
 .SS "Brands"
-.sp
-.LP
 A zone may be assigned a brand when it is initially created. A branded zone is
 one whose software does not match that software found in the global zone. The
 software may include Solaris software configured or laid out differently, or it
@@ -162,8 +154,6 @@ may include non-Solaris software. The particular collection of software is
 called a "brand" (see \fBbrands\fR(5)). Once installed, a zone's brand may not
 be changed unless the zone is first uninstalled.
 .SS "File Systems"
-.sp
-.LP
 Each zone has its own section of the file system hierarchy, rooted at a
 directory known as the zone root. Processes inside the zone can access only
 files within that part of the hierarchy, that is, files that are located
@@ -182,9 +172,15 @@ in multiple zones, while preserving the security guarantees supplied by zones.
 NFS and autofs mounts established within a zone are local to that zone; they
 cannot be accessed from other zones, including the global zone. The mounts are
 removed when the zone is halted or rebooted.
-.SS "Networking"
 .sp
 .LP
+A zone can share filesystems using \fBnfs\fR(4) or \fBsmb\fR(4)
+subject to the restrictions earlier in this section, plus the additional
+restriction that file sharing can only be done from filesystems a zone
+completely controls. Some \fBbrands\fR(5) do not have the zone root set to a
+filesystem boundary.  \fBsharefs\fR(7FS) can instantiate per-zone subject to
+the brand restrictions.
+.SS "Networking"
 A zone has its own port number space for \fBTCP\fR, \fBUDP\fR, and \fBSCTP\fR
 applications and typically one or more separate \fBIP\fR addresses (but some
 configurations of Trusted Extensions share IP address(es) between zones).
@@ -230,8 +226,6 @@ The full \fBIP\fR-level functionality in the form of \fBDHCP\fR client,
 \fBIPsec\fR and \fBIP\fR Filter, is available in exclusive-\fBIP\fR zones and
 not in shared-\fBIP\fR zones.
 .SS "Host Identifiers"
-.sp
-.LP
 A zone is capable of emulating a 32-bit host identifier, which can be
 configured via \fBzonecfg\fR(1M), for the purpose of system consolidation. If a
 zone emulates a host identifier, then commands such as \fBhostid\fR(1) and
@@ -240,10 +234,9 @@ zone emulates a host identifier, then commands such as \fBhostid\fR(1) and
 display or return the zone's emulated host identifier rather than the host
 machine's identifier.
 .SH SEE ALSO
-.sp
-.LP
 \fBhostid\fR(1), \fBzlogin\fR(1), \fBzonename\fR(1), \fBin.rlogind\fR(1M),
 \fBsshd\fR(1M), \fBsysdef\fR(1M), \fBzoneadm\fR(1M), \fBzonecfg\fR(1M),
 \fBkill\fR(2), \fBpriocntl\fR(2), \fBsysinfo\fR(2), \fBgethostid\fR(3C),
-\fBgetzoneid\fR(3C), \fBucred_get\fR(3C), \fBproc\fR(4), \fBattributes\fR(5),
-\fBbrands\fR(5), \fBprivileges\fR(5), \fBcrgetzoneid\fR(9F)
+\fBgetzoneid\fR(3C), \fBucred_get\fR(3C), \fBnfs\fR(4), \fBproc\fR(4),
+\fBsmb\fR(4), \fBattributes\fR(5), \fBbrands\fR(5), \fBprivileges\fR(5),
+\fBsharefs\fR(7FS), \fBcrgetzoneid\fR(9F)
diff --git a/usr/src/man/man7fs/sharefs.7fs b/usr/src/man/man7fs/sharefs.7fs
index 860d2aeeb5..f79febc992 100644
--- a/usr/src/man/man7fs/sharefs.7fs
+++ b/usr/src/man/man7fs/sharefs.7fs
@@ -3,19 +3,19 @@
 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH SHAREFS 7FS "Oct 31, 2007"
+.\"
+.\" Copyright 2020 Joyent, Inc.
+.TH SHAREFS 7FS "February 4, 2020"
 .SH NAME
 sharefs \- Kernel sharetab filesystem
 .SH DESCRIPTION
+The \fBsharefs\fR filesystem describes the state of all shares currently
+loaded by the kernel, and shared by the invoking zone. It is mounted during
+boot time as a read-only file at \fB/etc/dfs/sharetab\fR.
 .sp
 .LP
-The \fBsharefs\fR filesystem describes the state of all shares currently loaded
-by the kernel. It is mounted during boot time as a read-only file at
-\fB/etc/dfs/sharetab\fR.
-.sp
-.LP
-Filesystem contents are dynamic and  reflect  the current set of shares in the
-system. File contents are described in \fBsharetab\fR(4).
+Filesystem contents are dynamic and reflect the current set of shares in the
+zone. File contents are described in \fBsharetab\fR(4).
 .sp
 .LP
 File contents can be modified as a result of \fBshare\fR(1M),
@@ -25,7 +25,6 @@ File contents can be modified as a result of \fBshare\fR(1M),
 .LP
 The module may not be unloaded dynamically by the kernel.
 .SH FILES
-.sp
 .ne 2
 .na
 \fB\fB/etc/dfs/sharetab\fR\fR
@@ -35,7 +34,5 @@ System record of shared file systems.
 .RE
 
 .SH SEE ALSO
-.sp
-.LP
 \fBshare\fR(1M), \fBsharectl\fR(1M), \fBsharemgr\fR(1M), \fBzfs\fR(1M),
-\fBsharetab\fR(4)
+\fBsharetab\fR(4), \fBzones\fR(5)