[PATCH 1/9] Manual pages: nsenter.1, unshare.1: update references to *_namespaces(7) pages

[PATCH 1/9] Manual pages: nsenter.1, unshare.1: update references to *_namespaces(7) pages

[Michael Kerrisk]

Nowadays, the Linux man-pages project provides separate Section 7
manual pages for each type of namespace. Update the cross references
in nsenter.1 and unshare.1 to reflect this.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 sys-utils/nsenter.1 | 6 +++---
 sys-utils/unshare.1 | 6 +++---
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/sys-utils/nsenter.1 b/sys-utils/nsenter.1
index 424e22dc9..2f45df66d 100644
--- a/sys-utils/nsenter.1
+++ b/sys-utils/nsenter.1
@@ -27,7 +27,7 @@ flag in
 .B UTS namespace
 Setting hostname or domainname will not affect the rest of the system.
 For further details, see
-.BR namespaces (7)
+.BR uts_namespaces (7)
 and the discussion of the
 .B CLONE_NEWUTS
 flag in
@@ -38,7 +38,7 @@ The process will have an independent namespace for POSIX message queues
 as well as System V message queues,
 semaphore sets and shared memory segments.
 For further details, see
-.BR namespaces (7)
+.BR ipc_namespaces (7)
 and the discussion of the
 .B CLONE_NEWIPC
 flag in
@@ -52,7 +52,7 @@ and
 .I /sys\:/class\:/net
 directory trees, sockets, etc.
 For further details, see
-.BR namespaces (7)
+.BR network_namespaces (7)
 and the discussion of the
 .B CLONE_NEWNET
 flag in
diff --git a/sys-utils/unshare.1 b/sys-utils/unshare.1
index 7b35bc0b6..2665ca0af 100644
--- a/sys-utils/unshare.1
+++ b/sys-utils/unshare.1
@@ -48,7 +48,7 @@ Note that \fBprivate\fP is the kernel default.
 .B UTS namespace
 Setting hostname or domainname will not affect the rest of the system.
 For further details, see
-.BR namespaces (7)
+.BR uts_namespaces (7)
 and the discussion of the
 .B CLONE_NEWUTS
 flag in
@@ -59,7 +59,7 @@ The process will have an independent namespace for POSIX message queues
 as well as System V \%message queues,
 semaphore sets and shared memory segments.
 For further details, see
-.BR namespaces (7)
+.BR ipc_namespaces (7)
 and the discussion of the
 .B CLONE_NEWIPC
 flag in
@@ -70,7 +70,7 @@ The process will have independent IPv4 and IPv6 stacks, IP routing tables,
 firewall rules, the \fI/proc/net\fP and \fI/sys/class/net\fP directory trees,
 sockets, etc.
 For further details, see
-.BR namespaces (7)
+.BR network_namespaces (7)
 and the discussion of the
 .B CLONE_NEWNET
 flag in
-- 
2.26.2

[PATCH 2/9] Manual pages: nsenter.1, unshare.1: add a reference to time_namespaces(7)

[Michael Kerrisk]

Linux man-pages now has a page describing time namespaces.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 sys-utils/nsenter.1 | 2 ++
 sys-utils/unshare.1 | 2 ++
 2 files changed, 4 insertions(+)

diff --git a/sys-utils/nsenter.1 b/sys-utils/nsenter.1
index 2f45df66d..299107609 100644
--- a/sys-utils/nsenter.1
+++ b/sys-utils/nsenter.1
@@ -99,6 +99,8 @@ The process can have a distinct view of
 and/or
 .B CLOCK_BOOTTIME
 which can be changed using \fI/proc/self/timens_offsets\fP.
+For further details, see
+.BR time_namespaces (7).
 .TP
 See \fBclone\fP(2) for the exact semantics of the flags.
 .SH OPTIONS
diff --git a/sys-utils/unshare.1 b/sys-utils/unshare.1
index 2665ca0af..db67b0d4c 100644
--- a/sys-utils/unshare.1
+++ b/sys-utils/unshare.1
@@ -111,6 +111,8 @@ The process can have a distinct view of
 and/or
 .B CLOCK_BOOTTIME
 which can be changed using \fI/proc/self/timens_offsets\fP.
+For further details, see
+.BR time_namespaces (7).
 .SH OPTIONS
 .TP
 .BR \-i , " \-\-ipc" [ =\fIfile ]
-- 
2.26.2

[PATCH 3/9] Manual pages: nsenter.1, unshare.1: remove repeated references to clone(2)

[Michael Kerrisk]

Back in commits f85b9777c2965671cd and 894efece9eb894, in the
description of each namespace type, I added repeated cross references
to clone(2). Drop these references. The Section 7 namespaces pages,
which are already noted in the nsenter(1) and unshare(1) manual pages,
provide much more relevant information. Furthermore, pointing the
reader at clone(2) is perhaps a little misleading, since the system
call underlying nsenter(1) is setns(2) and the system call underlying
unshare(1) is unshare(2).

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 sys-utils/nsenter.1 | 39 ++++++---------------------------------
 sys-utils/unshare.1 | 45 ++++++++-------------------------------------
 2 files changed, 14 insertions(+), 70 deletions(-)

diff --git a/sys-utils/nsenter.1 b/sys-utils/nsenter.1
index 299107609..ea924f909 100644
--- a/sys-utils/nsenter.1
+++ b/sys-utils/nsenter.1
@@ -27,22 +27,14 @@ flag in
 .B UTS namespace
 Setting hostname or domainname will not affect the rest of the system.
 For further details, see
-.BR uts_namespaces (7)
-and the discussion of the
-.B CLONE_NEWUTS
-flag in
-.BR clone (2).
+.BR uts_namespaces (7).
 .TP
 .B IPC namespace
 The process will have an independent namespace for POSIX message queues
 as well as System V message queues,
 semaphore sets and shared memory segments.
 For further details, see
-.BR ipc_namespaces (7)
-and the discussion of the
-.B CLONE_NEWIPC
-flag in
-.BR clone (2).
+.BR ipc_namespaces (7).
 .TP
 .B network namespace
 The process will have independent IPv4 and IPv6 stacks, IP routing tables,
@@ -52,11 +44,7 @@ and
 .I /sys\:/class\:/net
 directory trees, sockets, etc.
 For further details, see
-.BR network_namespaces (7)
-and the discussion of the
-.B CLONE_NEWNET
-flag in
-.BR clone (2).
+.BR network_namespaces (7).
 .TP
 .B PID namespace
 Children will have a set of PID to process mappings separate from the
@@ -67,31 +55,18 @@ will fork by default if changing the PID namespace, so that the new program
 and its children share the same PID namespace and are visible to each other.
 If \fB\-\-no\-fork\fP is used, the new program will be exec'ed without forking.
 For further details, see
-.BR pid_namespaces (7)
-and
-the discussion of the
-.B CLONE_NEWPID
-flag in
-.BR clone (2).
+.BR pid_namespaces (7).
 .TP
 .B user namespace
 The process will have a distinct set of UIDs, GIDs and capabilities.
 For further details, see
-.BR user_namespaces (7)
-and the discussion of the
-.B CLONE_NEWUSER
-flag in
-.BR clone (2).
+.BR user_namespaces (7).
 .TP
 .B cgroup namespace
 The process will have a virtualized view of \fI/proc\:/self\:/cgroup\fP, and new
 cgroup mounts will be rooted at the namespace cgroup root.
 For further details, see
-.BR cgroup_namespaces (7)
-and the discussion of the
-.B CLONE_NEWCGROUP
-flag in
-.BR clone (2).
+.BR cgroup_namespaces (7).
 .TP
 .B time namespace
 The process can have a distinct view of
@@ -101,8 +76,6 @@ and/or
 which can be changed using \fI/proc/self/timens_offsets\fP.
 For further details, see
 .BR time_namespaces (7).
-.TP
-See \fBclone\fP(2) for the exact semantics of the flags.
 .SH OPTIONS
 Various of the options below that relate to namespaces take an optional
 .I file
diff --git a/sys-utils/unshare.1 b/sys-utils/unshare.1
index db67b0d4c..fb769d607 100644
--- a/sys-utils/unshare.1
+++ b/sys-utils/unshare.1
@@ -32,12 +32,8 @@ except for filesystems which are explicitly marked as
 shared (with \fBmount \-\-make-shared\fP; see \fI/proc/self/mountinfo\fP or
 \fBfindmnt \-o+PROPAGATION\fP for the \fBshared\fP flags).
 For further details, see
-.BR mount_namespaces (7)
-and the discussion of the
-.B CLONE_NEWNS
-flag in
-.BR clone (2).
-.sp
+.BR mount_namespaces (7).
+.IP
 .B unshare
 since util-linux version 2.27 automatically sets propagation to \fBprivate\fP
 in a new mount namespace to make sure that the new namespace is really
@@ -48,62 +44,37 @@ Note that \fBprivate\fP is the kernel default.
 .B UTS namespace
 Setting hostname or domainname will not affect the rest of the system.
 For further details, see
-.BR uts_namespaces (7)
-and the discussion of the
-.B CLONE_NEWUTS
-flag in
-.BR clone (2).
+.BR uts_namespaces (7).
 .TP
 .B IPC namespace
 The process will have an independent namespace for POSIX message queues
 as well as System V \%message queues,
 semaphore sets and shared memory segments.
 For further details, see
-.BR ipc_namespaces (7)
-and the discussion of the
-.B CLONE_NEWIPC
-flag in
-.BR clone (2).
+.BR ipc_namespaces (7).
 .TP
 .B network namespace
 The process will have independent IPv4 and IPv6 stacks, IP routing tables,
 firewall rules, the \fI/proc/net\fP and \fI/sys/class/net\fP directory trees,
 sockets, etc.
 For further details, see
-.BR network_namespaces (7)
-and the discussion of the
-.B CLONE_NEWNET
-flag in
-.BR clone (2).
+.BR network_namespaces (7).
 .TP
 .B PID namespace
 Children will have a distinct set of PID-to-process mappings from their parent.
 For further details, see
-.BR pid_namespaces (7)
-and
-the discussion of the
-.B CLONE_NEWPID
-flag in
-.BR clone (2).
+.BR pid_namespaces (7).
 .TP
 .B cgroup namespace
 The process will have a virtualized view of \fI/proc\:/self\:/cgroup\fP, and new
 cgroup mounts will be rooted at the namespace cgroup root.
 For further details, see
-.BR cgroup_namespaces (7)
-and the discussion of the
-.B CLONE_NEWCGROUP
-flag in
-.BR clone (2).
+.BR cgroup_namespaces (7).
 .TP
 .B user namespace
 The process will have a distinct set of UIDs, GIDs and capabilities.
 For further details, see
-.BR user_namespaces (7)
-and the discussion of the
-.B CLONE_NEWUSER
-flag in
-.BR clone (2).
+.BR user_namespaces (7).
 .TP
 .B time namespace
 The process can have a distinct view of
-- 
2.26.2

[PATCH 4/9] Manual pages: unshare.1: improve intro paragraphs

[Michael Kerrisk]

The intro paragraphs of this page are rather hard for a newcomer to
grok. The name of the underlying system call (and consequently the
name of the command) are "strange", but let's help the reader by
naming more clearly what unshare(1) does: creating new namespaces. In
addition, clarify and expand the details on making a namespace
persistent using bind mounts.

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

diff --git a/sys-utils/unshare.1 b/sys-utils/unshare.1
index fb769d607..14b107d37 100644
--- a/sys-utils/unshare.1
+++ b/sys-utils/unshare.1
@@ -1,30 +1,41 @@
 .TH UNSHARE 1 "February 2016" "util-linux" "User Commands"
 .SH NAME
-unshare \- run program with some namespaces unshared from parent
+unshare \- run program in new namespaces
 .SH SYNOPSIS
 .B unshare
 [options]
 .RI [ program
 .RI [ arguments ]]
 .SH DESCRIPTION
-Unshares the indicated namespaces from the parent process and then executes
-the specified \fIprogram\fR. If \fIprogram\fR is not given, then ``${SHELL}'' is
+The
+.B unshare
+command creates new namespaces
+(as specified by the command-line options described below)
+and then executes the specified \fIprogram\fR.
+If \fIprogram\fR is not given, then ``${SHELL}'' is
 run (default: /bin/sh).
 .PP
-The namespaces can optionally be made persistent by bind mounting
-/proc/\fIpid\fR/ns/\fItype\fR files to a filesystem path and entered with
+By default, a new namespace persists only as long as it has member processes.
+A new namespace can be made persistent even when it has no member processes
+by bind mounting
+/proc/\fIpid\fR/ns/\fItype\fR files to a filesystem path.
+A namespace that has been made persistent in this was can subsequently
+be entered with
 .BR \%nsenter (1)
 even after the \fIprogram\fR terminates (except PID namespaces where
-permanently running init process is required).
-Once a persistent \%namespace is no longer needed, it can be unpersisted with
-.BR umount (8).
+a permanently running init process is required).
+Once a persistent \%namespace is no longer needed,
+it can be unpersisted by using
+.BR umount (8)
+to remove the bind mount.
 See the \fBEXAMPLE\fR section for more details.
 .PP
 .B unshare
 since util-linux version 2.36 uses /\fIproc/[pid]/ns/pid_for_children\fP and \fI/proc/[pid]/ns/time_for_children\fP
 files for persistent PID and TIME namespaces. This change requires Linux kernel 4.17 or newer.
 .PP
-The namespaces to be unshared are indicated via options.  Unshareable namespaces are:
+The following types of namespaces can be created with
+.BR unshare :
 .TP
 .B mount namespace
 Mounting and unmounting filesystems will not affect the rest of the system,
-- 
2.26.2

[PATCH 5/9] Manual pages: nsenter.1: clarify the intro discussion

[Michael Kerrisk]

The intro paragraph talks about entering the namespace of other
processes. That's not quite accurate, since nsenter can be used (via
a bind mount) to enter a namespace that has no member processes.  So
rework NAME and the intro paragraph in DESCRIPTION to remove mention
of "processes".

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 sys-utils/nsenter.1 | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/sys-utils/nsenter.1 b/sys-utils/nsenter.1
index ea924f909..147137bd8 100644
--- a/sys-utils/nsenter.1
+++ b/sys-utils/nsenter.1
@@ -1,14 +1,19 @@
 .TH NSENTER 1 "June 2013" "util-linux" "User Commands"
 .SH NAME
-nsenter \- run program with namespaces of other processes
+nsenter \- run program in different namespaces
 .SH SYNOPSIS
 .B nsenter
 [options]
 .RI [ program
 .RI [ arguments ]]
 .SH DESCRIPTION
-Enters the namespaces of one or more other processes and then executes the specified
-\fIprogram\fP. If \fIprogram\fP is not given, then ``${SHELL}'' is run (default: /bin\:/sh).
+The
+.B nsenter
+command executes
+.I program
+in the namespace(s) that are specified in the command-line options
+(described below).
+If \fIprogram\fP is not given, then ``${SHELL}'' is run (default: /bin\:/sh).
 .PP
 Enterable namespaces are:
 .TP
-- 
2.26.2

[PATCH 6/9] Manual pages: nsenter.1: note that 'file' can be a bind mount

[Michael Kerrisk]

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 sys-utils/nsenter.1 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/sys-utils/nsenter.1 b/sys-utils/nsenter.1
index 147137bd8..5674f8d61 100644
--- a/sys-utils/nsenter.1
+++ b/sys-utils/nsenter.1
@@ -88,7 +88,8 @@ argument.
 This should be one of the
 .I /proc/[pid]/ns/*
 files described in
-.BR namespaces (7).
+.BR namespaces (7),
+or the pathname of a bind mount that was created on one of those files.
 .TP
 \fB\-a\fR, \fB\-\-all\fR
 Enter all namespaces of the target process by the default
-- 
2.26.2

[PATCH 7/9] Manual pages: unshare.1: fix examples, part 1

[Michael Kerrisk]

The examples section of this manual page is rather hard to grok.
First, the arrangement of the text as follows makes life harder
than needed for the reader:

    shell demo
        explanatory text

It helps the reader if an example *begins* with an explanation of
what is being demonstrated. Therefore, rearrange these examples as:

    explanatory text
        shell demo

In addition, let's provide a bit more explanation for the first three
examples and expand the second example (user namespaces) a little.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 sys-utils/unshare.1 | 109 +++++++++++++++++++++++++++++---------------
 1 file changed, 72 insertions(+), 37 deletions(-)

diff --git a/sys-utils/unshare.1 b/sys-utils/unshare.1
index 14b107d37..b8ef371a0 100644
--- a/sys-utils/unshare.1
+++ b/sys-utils/unshare.1
@@ -244,61 +244,96 @@ restricted so that a less privileged user can not get more access to sensitive
 files that a more privileged user made unavailable. In short the rule for proc
 and sysfs is as close to a bind mount as possible.
 .SH EXAMPLE
-.TP
+.PP
+The following command creates a PID namespace, using
+.B \-\-fork
+to ensure that the executed command is performed in a child process
+that (being the first process in the namespace) has PID 1.
+The
+.B \-\-mount-proc
+option ensures that a new mount namespace is also simultaneously created
+and that a new
+.BR proc (5)
+filesystem is mounted that contains information corresponding to the new
+PID namespace.
+When the
+.BR readlink
+command terminates, the new namespaces are automatically torn down.
+.PP
+.in +4n
+.EX
 .B # unshare \-\-fork \-\-pid \-\-mount-proc readlink /proc/self
-.TQ
 1
-.br
-Establish a PID namespace, ensure we're PID 1 in it against a newly mounted
-procfs instance.
-.TP
-.B $ unshare \-\-map-root-user \-\-user sh \-c whoami
-.TQ
+.EE
+.in
+.PP
+As an unprivileged user, create a new user namespace where the user's
+credentials are mapped to the root IDs inside the namespace:
+.PP
+.in +4n
+.EX
+.B $ id \-u; id \-g
+1000
+1000
+.B $ unshare \-\-user \-\-map-root-user \e
+.B "        sh \-c \(aqwhoami; cat /proc/self/uid_map /proc/self/gid_map\(aq"
 root
-.br
-Establish a user namespace as an unprivileged user with a root user within it.
-.TP
+         0       1000          1
+         0       1000          1
+.EE
+.in
+.PP
+The first of the following commands creates a new persistent UTS namespace
+and modifies the hostname as seen in that namespace.
+The namespace is then entered with
+.BR nsenter (1)
+in order to display the modified hostname;
+this step demonstrates that the UTS namespace continues to exist
+even though the namespace had no member processes after the
+.B unshare
+command terminated.
+The namespace is then destroyed by removing the bind mount.
+.PP
+.in +4n
+.EX
 .B # touch /root/uts-ns
-.TQ
 .B # unshare \-\-uts=/root/uts-ns hostname FOO
-.TQ
 .B # nsenter \-\-uts=/root/uts-ns hostname
-.TQ
 FOO
-.TQ
 .B # umount /root/uts-ns
-.br
-Establish a persistent UTS namespace, and modify the hostname.  The namespace
-is then entered with \fBnsenter\fR.  The namespace is destroyed by unmounting
-the bind reference.
-.TP
+.EE
+.in
+.PP
+Establish a persistent mount namespace referenced by the bind mount
+/root/namespaces/mnt.  This example shows a portable solution, because it
+makes sure that the bind mount is created on a shared filesystem.
+.PP
+.in +4n
+.EX
 .B # mount \-\-bind /root/namespaces /root/namespaces
-.TQ
 .B # mount \-\-make-private /root/namespaces
-.TQ
 .B # touch /root/namespaces/mnt
-.TQ
 .B # unshare \-\-mount=/root/namespaces/mnt
-.br
-Establish a persistent mount namespace referenced by the bind mount
-/root/namespaces/mnt.  This example shows a portable solution, because it
-makes sure that the bind mount is created on a shared filesystem.
-.TP
-.B # unshare \-pf \-\-kill-child \-\- bash \-c "(sleep 999 &) && sleep 1000" &
-.TQ
-.B # pid=$!
-.TQ
-.B # kill $pid
-.br
+.EE
+.in
+.PP
 Reliable killing of subprocesses of the \fIprogram\fR.
 When \fBunshare\fR gets killed, everything below it gets killed as well.
 Without it, the children of \fIprogram\fR would have orphaned and
 been re-parented to PID 1.
-.TP
+.PP
+.in +4n
+.EX
+.B # unshare \-pf \-\-kill-child \-\- bash \-c "(sleep 999 &) && sleep 1000" &
+.B # pid=$!
+.B # kill $pid
+.EE
+.in
+.PP
+.in +4n
+.EX
 .B # unshare \-\-fork \-\-time \-\-boottime 100000000 uptime
-.TQ
  10:58:48 up 1158 days,  6:05,  1 user,  load average: 0.00, 0.00, 0.00
-
 .SH AUTHORS
 .UR dottedmag@dottedmag.net
 Mikhail Gusarov
-- 
2.26.2

[PATCH 8/9] Manual pages: unshare.1: fix examples, part 2

[Michael Kerrisk]

The explanation of the --kill-child example was quite confused and
also the example shell demo was broken because of quoting issues.

It is not the case that the *children* of 'program' would adopted by
init, but rather that 'program' itself (which would be running as PID
1 inside the namespace and is a child of 'unshare') would be adopted
by init.

Rework the --kill-child example. Add a lot more explanation, and
expand the example shell session to give the reader a much better
picture of what is going on.

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

diff --git a/sys-utils/unshare.1 b/sys-utils/unshare.1
index b8ef371a0..38f7a62cf 100644
--- a/sys-utils/unshare.1
+++ b/sys-utils/unshare.1
@@ -317,16 +317,58 @@ makes sure that the bind mount is created on a shared filesystem.
 .EE
 .in
 .PP
-Reliable killing of subprocesses of the \fIprogram\fR.
-When \fBunshare\fR gets killed, everything below it gets killed as well.
-Without it, the children of \fIprogram\fR would have orphaned and
-been re-parented to PID 1.
+The following commands demonstrate the use of the
+.B \-\-kill-child
+option when creating a PID namespace, in order to ensure that when
+.B unshare
+is killed, all of the processes within the PID namespace are killed.
+.PP
+.in +4n
+.EX
+.BR "# set +m                " "# Don't print job status messages"
+.B # unshare \-\-pid \-\-fork \-\-mount\-proc \-\-kill\-child \-\- \e
+.B "       bash \-\-norc \-c \(aq(sleep 555 &) && (ps a &) && sleep 999\(aq &"
+[1] 53456
+#     PID TTY      STAT   TIME COMMAND
+      1 pts/3    S+     0:00 sleep 999
+      3 pts/3    S+     0:00 sleep 555
+      5 pts/3    R+     0:00 ps a
+
+.BR "# ps h \-o 'comm' $!     " "# Show that background job is unshare(1)"
+unshare
+.BR "# kill $!               " "# Kill unshare(1)
+.B # pidof sleep
+.EE
+.in
+.PP
+The
+.B pidof
+command prints no output, because the
+.B sleep
+processes have been killed.
+More precisely, when the
+.B sleep
+process that has PID 1 in the namespace (i.e., the namespace's init process)
+was killed, this caused all other processes in the namespace to be killed.
+By contrast, a similar series of commands where the
+.B \-\-kill\-child
+option is not used shows that when
+.B unshare
+terminates, the processes in the PID namespace are not killed:
 .PP
 .in +4n
 .EX
-.B # unshare \-pf \-\-kill-child \-\- bash \-c "(sleep 999 &) && sleep 1000" &
-.B # pid=$!
-.B # kill $pid
+.B # unshare \-\-pid \-\-fork \-\-mount\-proc \-\- \e
+.B "       bash \-\-norc \-c \(aq(sleep 555 &) && (ps a &) && sleep 999\(aq &"
+[1] 53479
+#     PID TTY      STAT   TIME COMMAND
+      1 pts/3    S+     0:00 sleep 999
+      3 pts/3    S+     0:00 sleep 555
+      5 pts/3    R+     0:00 ps a
+
+.B # kill $!
+.B # pidof sleep
+53482 53480
 .EE
 .in
 .PP
-- 
2.26.2

[PATCH 9/9] Manual pages: unshare.1: fix examples, part 3

[Michael Kerrisk]

The time namespaces example had no explanatory text!  Add some.
Also, use the "uptime -p" option for output that is more compact
(and perhaps more readable).

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

diff --git a/sys-utils/unshare.1 b/sys-utils/unshare.1
index 38f7a62cf..679f93715 100644
--- a/sys-utils/unshare.1
+++ b/sys-utils/unshare.1
@@ -372,10 +372,17 @@ terminates, the processes in the PID namespace are not killed:
 .EE
 .in
 .PP
+The following example demonstrates the creation of a time namespace
+where the boottime clock is set to a point several years in the past:
+.PP
 .in +4n
 .EX
-.B # unshare \-\-fork \-\-time \-\-boottime 100000000 uptime
- 10:58:48 up 1158 days,  6:05,  1 user,  load average: 0.00, 0.00, 0.00
+.BR "# uptime \-p             " "# Show uptime in initial time namespace"
+up 21 hours, 30 minutes
+.B # unshare \-\-time \-\-fork \-\-boottime 300000000 uptime \-p
+up 9 years, 28 weeks, 1 day, 2 hours, 50 minutes
+.EE
+.in
 .SH AUTHORS
 .UR dottedmag@dottedmag.net
 Mikhail Gusarov
-- 
2.26.2

Re: [PATCH 1/9] Manual pages: nsenter.1, unshare.1: update references to *_namespaces(7) pages

[Karel Zak]

On Sat, May 23, 2020 at 08:43:17AM +0200, Michael Kerrisk wrote:
>  sys-utils/nsenter.1 | 6 +++---
>  sys-utils/unshare.1 | 6 +++---
>  2 files changed, 6 insertions(+), 6 deletions(-)

Applied all 9 patches, thanks.

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

Re: [PATCH 1/9] Manual pages: nsenter.1, unshare.1: update references to *_namespaces(7) pages

[Michael Kerrisk (man-pages)]

On 5/25/20 2:17 PM, Karel Zak wrote:
> On Sat, May 23, 2020 at 08:43:17AM +0200, Michael Kerrisk wrote:
>>  sys-utils/nsenter.1 | 6 +++---
>>  sys-utils/unshare.1 | 6 +++---
>>  2 files changed, 6 insertions(+), 6 deletions(-)
> 
> Applied all 9 patches, thanks.

Thanks, Karel.

A follow-up question. There was one piece of the unshare(1) examples
that I did not try to rework, because I simply don't understand it:

       Establish  a  persistent  mount  namespace  referenced by the bind
       mount /root/namespaces/mnt.  This example shows a  portable  solu‐
       tion,  because  it  makes sure that the bind mount is created on a
       shared filesystem.

           # mount --bind /root/namespaces /root/namespaces
           # mount --make-private /root/namespaces
           # touch /root/namespaces/mnt
           # unshare --mount=/root/namespaces/mnt

I think you wrote this example. What does the sentence "This example shows
a portable solution, because it makes sure that the bind mount is created
on a shared filesystem" mean? I think this needs clarification, and I'd try
to do so, but it's not clear to me what the sentence is trying to say.

Thanks,

Michael

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

Re: [PATCH 1/9] Manual pages: nsenter.1, unshare.1: update references to *_namespaces(7) pages

[Karel Zak]

On Mon, May 25, 2020 at 03:13:18PM +0200, Michael Kerrisk (man-pages) wrote:
> A follow-up question. There was one piece of the unshare(1) examples
> that I did not try to rework, because I simply don't understand it:
> v
>        Establish  a  persistent  mount  namespace  referenced by the bind
>        mount /root/namespaces/mnt.  This example shows a  portable  solu‐
>        tion,  because  it  makes sure that the bind mount is created on a
>        shared filesystem.
> 
>            # mount --bind /root/namespaces /root/namespaces
>            # mount --make-private /root/namespaces
>            # touch /root/namespaces/mnt
>            # unshare --mount=/root/namespaces/mnt
> 
> I think you wrote this example. What does the sentence "This example shows
> a portable solution, because it makes sure that the bind mount is created
> on a shared filesystem" mean? I think this needs clarification, and I'd try
> to do so, but it's not clear to me what the sentence is trying to say.

Hmm... it should be "the /root/namespaces/mnt is on a private
filesystem". The important thing is --make-private in this case,
because for example on Fedora we use "shared" propagation flag for
root FS and without bind + make-private you will be unsuccessful. The
example makes it portable between distros.

    Karel

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

Re: [PATCH 1/9] Manual pages: nsenter.1, unshare.1: update references to *_namespaces(7) pages

[Michael Kerrisk (man-pages)]

On Tue, 26 May 2020 at 10:50, Karel Zak <kzak@redhat.com> wrote:
>
> On Mon, May 25, 2020 at 03:13:18PM +0200, Michael Kerrisk (man-pages) wrote:
> > A follow-up question. There was one piece of the unshare(1) examples
> > that I did not try to rework, because I simply don't understand it:
> > v
> >        Establish  a  persistent  mount  namespace  referenced by the bind
> >        mount /root/namespaces/mnt.  This example shows a  portable  solu‐
> >        tion,  because  it  makes sure that the bind mount is created on a
> >        shared filesystem.
> >
> >            # mount --bind /root/namespaces /root/namespaces
> >            # mount --make-private /root/namespaces
> >            # touch /root/namespaces/mnt
> >            # unshare --mount=/root/namespaces/mnt
> >
> > I think you wrote this example. What does the sentence "This example shows
> > a portable solution, because it makes sure that the bind mount is created
> > on a shared filesystem" mean? I think this needs clarification, and I'd try
> > to do so, but it's not clear to me what the sentence is trying to say.
>
> Hmm... it should be "the /root/namespaces/mnt is on a private
> filesystem". The important thing is --make-private in this case,
> because for example on Fedora we use "shared" propagation flag for
> root FS and without bind + make-private you will be unsuccessful. The
> example makes it portable between distros.

Okay -- I'll send a patch, once the curent queue of patches I have
with you is cleared.

Thanks,

Michael


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