Util-Linux Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH 1/2] Manual pages: unshare.1: clarify description and example for --mount=<path>
@ 2020-06-03  7:40 Michael Kerrisk (man-pages)
  2020-06-03  7:40 ` [PATCH 2/2] Manual pages: unshare.1: clarify that --pid=<file> requires --fork Michael Kerrisk (man-pages)
  0 siblings, 1 reply; 4+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-06-03  7:40 UTC (permalink / raw)
  To: mtk.manpages, Karel Zak; +Cc: util-linux

The existing text is not quite accurate, and I recently injected an
error into the EXAMPLES. This patch fixes both issues.

The text in DESCRIPTION incorrectly states that the propagation type of
the parent mount must be "private". This is not accurate.  Rather, the
propagation type must be something *other than "shared"* (i.e.,
"private", "slave", or "unbindable").

In the EXAMPLES section, I added text that implies that if the
propagation type of the parent mount is "shared", then the child mount
created by --mount=<path> might propagate to another namespace.
Rather, in this situation, an error would result. Clarify that.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 sys-utils/unshare.1 | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/sys-utils/unshare.1 b/sys-utils/unshare.1
index a260d02e3..443aac658 100644
--- a/sys-utils/unshare.1
+++ b/sys-utils/unshare.1
@@ -104,8 +104,9 @@ namespace is created by a bind mount.
 .BR \-m , " \-\-mount" [ =\fIfile ]
 Unshare the mount namespace.  If \fIfile\fP is specified, then a persistent
 namespace is created by a bind mount.
-Note that \fIfile\fP has to be located on a filesystem with the propagation
-flag set to \fBprivate\fP.  Use the command \fBfindmnt \-o+PROPAGATION\fP
+Note that \fIfile\fP must be located on a mount whose propagation type
+is not \fBshared\fP (or an error results).
+Use the command \fBfindmnt \-o+PROPAGATION\fP
 when not sure about the current setting.  See also the examples below.
 .TP
 .BR \-n , " \-\-net" [ =\fIfile ]
@@ -307,13 +308,11 @@ FOO
 The following commands
 establish a persistent mount namespace referenced by the bind mount
 .IR /root/namespaces/mnt .
-In order to ensure that this bind mount does not get propagated
-to other mount namespaces,
+In order to ensure that the creation of that bind mount succeeds,
 the parent directory
 .RI ( /root/namespaces )
-is first made a bind mount with
-.I private
-propagation.
+is made a bind mount whose propagation type is not
+.BR shared .
 .PP
 .in +4n
 .EX
-- 
2.26.2


^ permalink raw reply	[flat|nested] 4+ messages in thread

* [PATCH 2/2] Manual pages: unshare.1: clarify that --pid=<file> requires --fork
  2020-06-03  7:40 [PATCH 1/2] Manual pages: unshare.1: clarify description and example for --mount=<path> Michael Kerrisk (man-pages)
@ 2020-06-03  7:40 ` Michael Kerrisk (man-pages)
  2020-06-03 10:22   ` Michael Kerrisk (man-pages)
  0 siblings, 1 reply; 4+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-06-03  7:40 UTC (permalink / raw)
  To: mtk.manpages, Karel Zak; +Cc: util-linux

Attempting to create a persistent PID namespace with --pid=<file>
will result in an error if --fork is not also specified. Let's
warn people about that, so they don't get puzzled.

Signed-off-by: Michael Kerrisk (man-pages) <mtk.manpages@gmail.com>
---
 sys-utils/unshare.1 | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/sys-utils/unshare.1 b/sys-utils/unshare.1
index 443aac658..7899db3ad 100644
--- a/sys-utils/unshare.1
+++ b/sys-utils/unshare.1
@@ -114,8 +114,13 @@ Unshare the network namespace.  If \fIfile\fP is specified, then a persistent
 namespace is created by a bind mount.
 .TP
 .BR \-p , " \-\-pid" [ =\fIfile ]
-Unshare the PID namespace.  If \fIfile\fP is specified then persistent
-namespace is created by a bind mount.  See also the \fB\-\-fork\fP and
+Unshare the PID namespace.  If \fIfile\fP is specified, then a persistent
+namespace is created by a bind mount.
+(Creation of a persistent PID namespace will fail if the
+.B \-\-fork
+is not also specified.)
+.IP
+See also the \fB\-\-fork\fP and
 \fB\-\-mount-proc\fP options.
 .TP
 .BR \-u , " \-\-uts" [ =\fIfile ]
-- 
2.26.2


^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH 2/2] Manual pages: unshare.1: clarify that --pid=<file> requires --fork
  2020-06-03  7:40 ` [PATCH 2/2] Manual pages: unshare.1: clarify that --pid=<file> requires --fork Michael Kerrisk (man-pages)
@ 2020-06-03 10:22   ` Michael Kerrisk (man-pages)
  2020-06-03 15:06     ` Karel Zak
  0 siblings, 1 reply; 4+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-06-03 10:22 UTC (permalink / raw)
  To: Michael Kerrisk, Karel Zak; +Cc: util-linux

> +(Creation of a persistent PID namespace will fail if the
> +.B \-\-fork
> +is not also specified.)

Small wording problem there... s/is/option is/

Should I send a new patch, or will you hand edit?

Thanks,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: [PATCH 2/2] Manual pages: unshare.1: clarify that --pid=<file> requires --fork
  2020-06-03 10:22   ` Michael Kerrisk (man-pages)
@ 2020-06-03 15:06     ` Karel Zak
  0 siblings, 0 replies; 4+ messages in thread
From: Karel Zak @ 2020-06-03 15:06 UTC (permalink / raw)
  To: Michael Kerrisk (man-pages); +Cc: util-linux

On Wed, Jun 03, 2020 at 12:22:46PM +0200, Michael Kerrisk (man-pages) wrote:
> > +(Creation of a persistent PID namespace will fail if the
> > +.B \-\-fork
> > +is not also specified.)
> 
> Small wording problem there... s/is/option is/

Applied & fixed, thanks!

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com


^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, back to index

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-06-03  7:40 [PATCH 1/2] Manual pages: unshare.1: clarify description and example for --mount=<path> Michael Kerrisk (man-pages)
2020-06-03  7:40 ` [PATCH 2/2] Manual pages: unshare.1: clarify that --pid=<file> requires --fork Michael Kerrisk (man-pages)
2020-06-03 10:22   ` Michael Kerrisk (man-pages)
2020-06-03 15:06     ` Karel Zak

Util-Linux Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/util-linux/0 util-linux/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 util-linux util-linux/ https://lore.kernel.org/util-linux \
		util-linux@vger.kernel.org
	public-inbox-index util-linux

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.util-linux


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git