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
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.
--- sys-utils/nsenter.1 | 6 +++--- sys-utils/unshare.1 | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-)
sys-utils/nsenter.1 +3 -3
@@ -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
sys-utils/unshare.1 +3 -3
@@ -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
Signature · 1 line
2.26.2
PATCH 2/9 Manual pages: nsenter.1, unshare.1: add a reference to time_namespaces(7)
Linux man-pages now has a page describing time namespaces.
--- sys-utils/nsenter.1 | 2 ++ sys-utils/unshare.1 | 2 ++ 2 files changed, 4 insertions(+)
sys-utils/nsenter.1 +2 -0
@@ -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
sys-utils/unshare.1 +2 -0
@@ -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 ]
Signature · 1 line
2.26.2
PATCH 3/9 Manual pages: nsenter.1, unshare.1: remove repeated references to clone(2)
In reply to Michael KerriskBack 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).
--- sys-utils/nsenter.1 | 39 ++++++--------------------------------- sys-utils/unshare.1 | 45 ++++++++------------------------------------- 2 files changed, 14 insertions(+), 70 deletions(-)
sys-utils/nsenter.1 +6 -33
@@ -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
sys-utils/unshare.1 +8 -37
82 lines not on this page · raw message
Signature · 1 line
2.26.2
PATCH 4/9 Manual pages: unshare.1: improve intro paragraphs
In reply to Michael KerriskThe 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.
--- sys-utils/unshare.1 | 29 ++++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-)
sys-utils/unshare.1 +20 -9
@@ -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,
Signature · 1 line
2.26.2
PATCH 5/9 Manual pages: nsenter.1: clarify the intro discussion
In reply to Michael KerriskThe 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".
--- sys-utils/nsenter.1 | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-)
sys-utils/nsenter.1 +8 -3
@@ -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
Signature · 1 line
2.26.2
PATCH 6/9 Manual pages: nsenter.1: note that 'file' can be a bind mount
In reply to Michael Kerrisk--- sys-utils/nsenter.1 | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
sys-utils/nsenter.1 +2 -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
Signature · 1 line
2.26.2
PATCH 7/9 Manual pages: unshare.1: fix examples, part 1
In reply to Michael KerriskThe 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.
--- sys-utils/unshare.1 | 109 +++++++++++++++++++++++++++++--------------- 1 file changed, 72 insertions(+), 37 deletions(-)
sys-utils/unshare.1 +72 -37
@@ -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 [email protected] Mikhail Gusarov
Signature · 1 line
2.26.2
PATCH 8/9 Manual pages: unshare.1: fix examples, part 2
In reply to Michael KerriskThe 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.
--- sys-utils/unshare.1 | 56 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 49 insertions(+), 7 deletions(-)
sys-utils/unshare.1 +49 -7
@@ -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
Signature · 1 line
2.26.2
PATCH 9/9 Manual pages: unshare.1: fix examples, part 3
In reply to Michael KerriskThe 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).
--- sys-utils/unshare.1 | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-)
sys-utils/unshare.1 +9 -2
@@ -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 [email protected] Mikhail Gusarov
Signature · 1 line
2.26.2
Quoted 3 lines · Michael Kerrisk
sys-utils/nsenter.1 | 6 +++--- sys-utils/unshare.1 | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-)
Applied all 9 patches, thanks.
Signature · 2 lines
Karel Zak <[email protected]> http://karelzak.blogspot.com
Quoted 6 lines · Karel Zak
Quoted 3 lines · Michael Kerrisk
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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/
Karel Zak
maintainerQuoted 13 lines · Michael Kerrisk (man-pages)
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
Quoted 4 lines
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
Signature · 2 lines
Karel Zak <[email protected]> http://karelzak.blogspot.com
Quoted 20 lines · Karel Zak
Quoted 13 lines · Michael Kerrisk (man-pages)
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/mntQuoted 4 lines
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.
Quoted 5 lines
Hmm... it should be "the
/root/namespaces/mntis 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
Signature · 3 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/