Documentation for CLONE_NEWPID
Pavel, Kir,
Drawing fairly heavily on your LWN.net article (http://lwn.net/Articles/259217/), plus the kernel source and some experimentation, I created the patch below to document CLONE_NEWPID for the clone(2) manual page. Could you please review and let me know of any improvements or inaccuracies.
Thanks,
Michael
man2/clone.2 +82 -0
@@ -266,6 +268,78 @@ in the same .BR clone () call. .TP +.BR CLONE_NEWPID " (since Linux 2.6.24)" +.\" This explanation draws a lot of details from +.\" http://lwn.net/Articles/259217/ +.\" Authors: Pavel Emelyanov <[email protected]> +.\" and Kir Kolyshkin <[email protected]> +.\" +.\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264 +.\" Author: Pavel Emelyanov <[email protected]> +If +.B CLONE_PID +is set, then create the process in a new PID namespace. +If this flag is not set, then (as with +.BR fork (2)), +the process is created in the same PID namespace as +the calling process. +This flag is intended for the implementation of control groups. + +A PID namespace provides an isolated environment for PIDs: +PIDs in a new namespace start at 1, +somewhat like a standalone system, and calls to +.BR fork (2), +.BR vfork (2), +or +.BR clone (2) +will produce processes whose PIDs within the namespace +are only guaranteed to be unique within that namespace. + +The first process created in a new namespace +(i.e., the process created using the +.BR CLONE_NEWPID +flag) has the PID 1, and is the "init" process for the namespace. +Children that are orphaned within the namespace will be reparented +to this process rather than +.BR init (8). +Unlike the traditional +.B init +process, the "init" process of a PID namespace can terminate, +and if it does, all of the processes in the namespace are terminated. + +PID namespaces form a hierarchy. +When a PID new namespace is created, +the PIDs of the processes in that namespace are visible +in the PID namespace of the process that created the new namespace; +analogously, if the parent PID namespace is itself +the child of another PID namespace, +then PIDs of the child and parent PID namespaces will both be +visible in the grandparent PID namespace. +Conversely, the processes in the "child" PID namespace do not see +the PIDs of the processes in the parent namespace. +The existence of a namespace hierarchy means that each process +may now have multiple PIDs: +one for each namespace in which it is visible. +(A call to +.BR getpid (2) +always returns the PID associated with the namespace in which +the process was created.) + +After creating the new namespace, +it is useful for the child to change its root directory +and mount a new procfs instance at +.I /proc +so that tools such as +.BR ps (1) +work correctly. + +Use of this flag requires: a kernel configured with the +.B CONFIG_PID_NS +configuration option and requires that the process be privileged +.RB (CAP_SYS_ADMIN ). +This flag can't be specified in conjunction with +.BR CLONE_THREAD . +.TP .BR CLONE_PARENT " (since Linux 2.3.12)" If .B CLONE_PARENT
@@ -627,6 +701,14 @@ were specified in .IR flags . .TP .B EINVAL +Both +.BR CLONE_NEWPID +and +.BR CLONE_THREAD +were specified in +.IR flags . +.TP +.B EINVAL Returned by .BR clone () when a zero value is specified for
@@ -639,6 +721,8 @@ copied. .TP .B EPERM .B CLONE_NEWNS +or +.B CLONE_NEWPID was specified by a non-root process (process without \fBCAP_SYS_ADMIN\fP). .TP .B EPERM
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 7 lines · Michael Kerrisk
Pavel, Kir,
Drawing fairly heavily on your LWN.net article
(http://lwn.net/Articles/259217/), plus the kernel source and some experimentation, I created the patch below to documentCLONE_NEWPIDfor the clone(2) manual page. Could you please review and let me know of any improvements or inaccuracies.
Thanks, Michael, this is something we've definately been wanting to get to.
...
Quoted 4 lines
man2/clone.2 +4
-0+(i.e., the process created using the +.BR CLONE_NEWPID +flag) has the PID 1, and is the "init" process for the namespace. +Children that are orphaned within the namespace will be reparented
man2/clone.2 in the same · line 312
Quoted 10 lines
man2/clone.2 +10
-0+to this process rather than +.BR init (8). +Unlike the traditional +.B init +process, the "init" process of a PID namespace can terminate, +and if it does, all of the processes in the namespace are terminated. + +PID namespaces form a hierarchy. +When a PID new namespace is created, +the PIDs of the processes in that namespace are visible
The processes in that namespace are visible, but by different pids. So saying that the pids are visible in the parent pidns isn't quite right.
man2/clone.2 in the same · line 316
Quoted 4 lines
man2/clone.2 +4
-0+in the PID namespace of the process that created the new namespace; +analogously, if the parent PID namespace is itself +the child of another PID namespace, +then PIDs of the child and parent PID namespaces will both be
Again, the processes, not pids, are visible.
Quoted 8 lines
man2/clone.2 +8
-0+visible in the grandparent PID namespace. +Conversely, the processes in the "child" PID namespace do not see +the PIDs of the processes in the parent namespace. +The existence of a namespace hierarchy means that each process +may now have multiple PIDs: +one for each namespace in which it is visible. +(A call to +.BR getpid (2)
man2/clone.2 in the same · line 334
Quoted 10 lines
man2/clone.2 +10
-0+always returns the PID associated with the namespace in which +the process was created.) + +After creating the new namespace, +it is useful for the child to change its root directory +and mount a new procfs instance at +.I /proc +so that tools such as +.BR ps (1) +work correctly.
Probably not worth mentioning here, but if it has done CLONE_NEWNS then it doesn't need to change its root, it can just mount a new proc instance over /proc.
Quoted 27 lines
man2/clone.2 +16
-0+ +Use of this flag requires: a kernel configured with the +.B CONFIG_PID_NS +configuration option and requires that the process be privileged +.RB (CAP_SYS_ADMIN ). +This flag can't be specified in conjunction with +.BR CLONE_THREAD . +.TP .BR CLONE_PARENT " (since Linux 2.3.12)" If .B CLONE_PARENT@@ -627,6 +701,14 @@ were specified in .IR flags . .TP .B EINVAL +Both +.BR CLONE_NEWPID +and +.BR CLONE_THREAD +were specified in +.IR flags . +.TP +.B EINVAL Returned by .BR clone () when a zero value is specified for
man2/clone.2 copied. · line 728
Quoted 8 lines
man2/clone.2 +2
-0@@ -639,6 +721,8 @@ copied. .TP .B EPERM .B CLONE_NEWNS +or +.B CLONE_NEWPID was specified by a non-root process (process without \fBCAP_SYS_ADMIN\fP). .TP .B EPERM
I assume you've considered the pros and cons of mentioning signal semantics with respect to init tasks of child pid namespaces, and decided it's not worth mentioning yet as the semantics are not yet finalized?
The goal is to treat the process as a system-wide init with respect to signals coming from its own namespace, and treat it as an ordinary task for signals coming from its ancestor namespaces. But as you've probably read, the implementation may result in some unfortunate side-effects regarding blocked signals etc.
thanks,
-serge
Hi Serge,
[...]
Quoted 7 lines
man2/clone.2 in the same · line 312
Quoted 3 lines
man2/clone.2 +3
-0+PID namespaces form a hierarchy. +When a PID new namespace is created, +the PIDs of the processes in that namespace are visibleThe processes in that namespace are visible, but by different pids. So saying that the pids are visible in the parent pidns isn't quite right.
Yes, good point. I made that last line:
"... the processes in that namespace are visible..."
Quoted 6 lines
man2/clone.2 in the same · line 316
Quoted 4 lines
man2/clone.2 +4
-0+in the PID namespace of the process that created the new namespace; +analogously, if the parent PID namespace is itself +the child of another PID namespace, +then PIDs of the child and parent PID namespaces will both beAgain, the processes, not pids, are visible.
Yep. Fixed.
[...]
Quoted 11 lines
man2/clone.2 in the same · line 334
Quoted 7 lines
man2/clone.2 +7
-0+After creating the new namespace, +it is useful for the child to change its root directory +and mount a new procfs instance at +.I /proc +so that tools such as +.BR ps (1) +work correctly.Probably not worth mentioning here, but if it has done
CLONE_NEWNSthen it doesn't need to change its root, it can just mount a new proc instance over /proc.
Actually, I think it is worth mentioning. When I wrote the text, I suspected that the point you make here was true, but I wasn't 100% sure. Therefore, I think it worth adding a sentence like your comment here, and I've done so.
[...]
Quoted 10 lines
I assume you've considered the pros and cons of mentioning signal semantics with respect to init tasks of child pid namespaces, and decided it's not worth mentioning yet as the semantics are not yet finalized?
The goal is to treat the process as a system-wide init with respect to signals coming from its own namespace, and treat it as an ordinary task for signals coming from its ancestor namespaces. But as you've probably read, the implementation may result in some unfortunate side-effects regarding blocked signals etc.
No I haven't considered this at all. Could you provide some pointers to relevant discussions on this?
Cheers,
Michael
Signature · 5 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html
Quoted 6 lines · Michael Kerrisk
Hi Serge,
Quoted 5 lines
I assume you've considered the pros and cons of mentioning signal semantics with respect to init tasks of child pid namespaces, and decided it's not worth mentioning yet as the semantics are not yet finalized?
Quoted 8 lines
Quoted 5 lines
The goal is to treat the process as a system-wide init with respect to signals coming from its own namespace, and treat it as an ordinary task for signals coming from its ancestor namespaces. But as you've probably read, the implementation may result in some unfortunate side-effects regarding blocked signals etc.
No I haven't considered this at all. Could you provide some pointers to relevant discussions on this?
The discussions are going on right now on lkml (see for instance
http://lkml.org/lkml/2008/11/15/124). But I think Nadia has already written something up. Nadia, could you send what you have to Michael?
thanks,
-serge
Quoted 5 lines · Michael Kerrisk
Pavel, Kir,
Drawing fairly heavily on your LWN.net article (http://lwn.net/Articles/259217/), plus the kernel source and some experimentation, I created the patch below to document
CLONE_NEWPIDfor the clone(2) manual page. Could you please review and let me know of any improvements or inaccuracies.
Michael, sorry for the late response - I've been on vacation last week and didn't have chance to connect to check my mail. Some comments are inline.
Quoted 16 lines
Thanks,
Michael
man2/clone.2 +6
-0@@ -266,6 +268,78 @@ in the same .BR clone () call. .TP +.BR CLONE_NEWPID " (since Linux 2.6.24)" +.\" This explanation draws a lot of details from +.\" http://lwn.net/Articles/259217/ +.\" Authors: Pavel Emelyanov <[email protected]> +.\" and Kir Kolyshkin <[email protected]> +.\"
man2/clone.2 in the same · line 286
Quoted 10 lines
man2/clone.2 +10
-0+.\" The primary kernel commit is 30e49c263e36341b60b735cbef5ca37912549264 +.\" Author: Pavel Emelyanov <[email protected]> +If +.B CLONE_PID +is set, then create the process in a new PID namespace. +If this flag is not set, then (as with +.BR fork (2)), +the process is created in the same PID namespace as +the calling process. +This flag is intended for the implementation of control groups.
Well, actually this has nothing to do with control groups. This flag is intended to be used to facilitate the creation of containers along with many other clone flags. Control groups is yet another way to create a container.
man2/clone.2 in the same · line 296
Quoted 9 lines
man2/clone.2 +9
-0+A PID namespace provides an isolated environment for PIDs: +PIDs in a new namespace start at 1, +somewhat like a standalone system, and calls to +.BR fork (2), +.BR vfork (2), +or +.BR clone (2) +will produce processes whose PIDs within the namespace +are only guaranteed to be unique within that namespace.
Well, I'm not sure I understood correctly what was meant here, but after we have a namespace each task has two pids. And _all_ of them are unique in corresponding namespaces.
Quoted 19 lines
man2/clone.2 +19
-0+The first process created in a new namespace +(i.e., the process created using the +.BR CLONE_NEWPID +flag) has the PID 1, and is the "init" process for the namespace. +Children that are orphaned within the namespace will be reparented +to this process rather than +.BR init (8). +Unlike the traditional +.B init +process, the "init" process of a PID namespace can terminate, +and if it does, all of the processes in the namespace are terminated. + +PID namespaces form a hierarchy. +When a PID new namespace is created, +the PIDs of the processes in that namespace are visible +in the PID namespace of the process that created the new namespace; +analogously, if the parent PID namespace is itself +the child of another PID namespace, +then PIDs of the child and parent PID namespaces will both be
man2/clone.2 in the same · line 326
Quoted 10 lines
man2/clone.2 +10
-0+visible in the grandparent PID namespace. +Conversely, the processes in the "child" PID namespace do not see +the PIDs of the processes in the parent namespace. +The existence of a namespace hierarchy means that each process +may now have multiple PIDs: +one for each namespace in which it is visible. +(A call to +.BR getpid (2) +always returns the PID associated with the namespace in which +the process was created.)
I don't thinks it's a good example - the getpid cannot be called for other process other than current :)
Quoted 36 lines
man2/clone.2 +24
-0+ +After creating the new namespace, +it is useful for the child to change its root directory +and mount a new procfs instance at +.I /proc +so that tools such as +.BR ps (1) +work correctly. + +Use of this flag requires: a kernel configured with the +.B CONFIG_PID_NS +configuration option and requires that the process be privileged +.RB (CAP_SYS_ADMIN ). +This flag can't be specified in conjunction with +.BR CLONE_THREAD . +.TP .BR CLONE_PARENT " (since Linux 2.3.12)" If .B CLONE_PARENT@@ -627,6 +701,14 @@ were specified in .IR flags . .TP .B EINVAL +Both +.BR CLONE_NEWPID +and +.BR CLONE_THREAD +were specified in +.IR flags . +.TP +.B EINVAL Returned by .BR clone () when a zero value is specified for
man2/clone.2 copied. · line 728
Quoted 8 lines
man2/clone.2 +2
-0@@ -639,6 +721,8 @@ copied. .TP .B EPERM .B CLONE_NEWNS +or +.B CLONE_NEWPID was specified by a non-root process (process without \fBCAP_SYS_ADMIN\fP). .TP .B EPERM
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Hi Pavel,
Quoted 9 lines · Pavel Emelyanov
Quoted 5 lines · Michael Kerrisk
Pavel, Kir,
Drawing fairly heavily on your LWN.net article (http://lwn.net/Articles/259217/), plus the kernel source and some experimentation, I created the patch below to document
CLONE_NEWPIDfor the clone(2) manual page. Could you please review and let me know of any improvements or inaccuracies.Michael, sorry for the late response - I've been on vacation last week and didn't have chance to connect to check my mail.
No problem.
Quoted 1 line
Some comments are inline.
Thanks!
[...]
Quoted 6 lines
Quoted 1 line
+This flag is intended for the implementation of control groups.
Well, actually this has nothing to do with control groups. This flag is intended to be used to facilitate the creation of containers along with many other clone flags. Control groups is yet another way to create a container.
Yep, after an earlier mail from Eric, I already changed this to "containers".
Quoted 11 lines
man2/clone.2 in the same · line 296
Quoted 9 lines
man2/clone.2 +9
-0+A PID namespace provides an isolated environment for PIDs: +PIDs in a new namespace start at 1, +somewhat like a standalone system, and calls to +.BR fork (2), +.BR vfork (2), +or +.BR clone (2) +will produce processes whose PIDs within the namespace +are only guaranteed to be unique within that namespace.Well, I'm not sure I understood correctly what was meant here, but after
I've simplified that sentence somewhat. Now it just reads:
A PID namespace provides an isolated environment for
PIDs: PIDs in a new namespace start at 1, somewhat like a standalone system, and calls to fork(2), vfork(2), or clone(2) will produce processes with PIDs that are unique within the namespace.
Quoted 2 lines
we have a namespace each task has two pids. And _all_ of them are unique in corresponding namespaces.
And I already make that point lower down in the text (see ***), but now I extended the sentence there a little.
[...]
*** Here's where I make the point about each process having multiple PIDs"
Quoted 3 lines
man2/clone.2 in the same · line 322
Quoted 3 lines
man2/clone.2 +3
-0+The existence of a namespace hierarchy means that each process +may now have multiple PIDs: +one for each namespace in which it is visible.
I added some words here:
"each of these PIDs is unique within the corresponding namespace".
Quoted 7 lines
man2/clone.2 in the same · line 326
Quoted 4 lines
man2/clone.2 +4
-0+(A call to +.BR getpid (2) +always returns the PID associated with the namespace in which +the process was created.)I don't thinks it's a good example - the getpid cannot be called for other process other than current :)
It wasn't meant as an example. The point was, with a process potentially being a member of multiple namespaces, the reader might
wonder: what does getpid(2) return? This sentence was intended to clarify that. With that explanation, does this sentence now seem okay?
[...]
Cheers,
Michael
Signature · 9 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Quoted 11 lines
Quoted 10 lines
man2/clone.2 in the same · line 296
Quoted 9 lines
man2/clone.2 +9
-0+A PID namespace provides an isolated environment for PIDs: +PIDs in a new namespace start at 1, +somewhat like a standalone system, and calls to +.BR fork (2), +.BR vfork (2), +or +.BR clone (2) +will produce processes whose PIDs within the namespace +are only guaranteed to be unique within that namespace.Well, I'm not sure I understood correctly what was meant here, but after
Quoted 7 lines
I've simplified that sentence somewhat. Now it just reads:
A PID namespace provides an isolated environment for
PIDs: PIDs in a new namespace start at 1, somewhat like a standalone system, and calls to fork(2), vfork(2), or clone(2) will produce processes with PIDs that are unique within the namespace.
OK, thanks.
Quoted 10 lines
Quoted 2 lines
we have a namespace each task has two pids. And _all_ of them are unique in corresponding namespaces.
And I already make that point lower down in the text (see ***), but now I extended the sentence there a little.
[...]
*** Here's where I make the point about each process having multiple PIDs"
Quoted 7 lines
Quoted 3 lines
man2/clone.2 in the same · line 322
Quoted 3 lines
man2/clone.2 +3
-0+The existence of a namespace hierarchy means that each process +may now have multiple PIDs: +one for each namespace in which it is visible.I added some words here:
"each of these PIDs is unique within the corresponding namespace".
Correct.
Quoted 7 lines
Quoted 6 lines
man2/clone.2 in the same · line 326
Quoted 4 lines
man2/clone.2 +4
-0+(A call to +.BR getpid (2) +always returns the PID associated with the namespace in which +the process was created.)I don't thinks it's a good example - the getpid cannot be called for other process other than current :)
Quoted 5 lines
It wasn't meant as an example. The point was, with a process potentially being a member of multiple namespaces, the reader might
wonder: what does getpid(2) return? This sentence was intended to clarify that. With that explanation, does this sentence now seem okay?
Yes, but I'd change "was created" into "lives in". From my POV this sounds more clear. I do not insist however :)
Quoted 6 lines
[...]
Cheers,
Michael
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
Hi Pavel,
[...]
Quoted 11 lines
Quoted 9 lines
*** Here's where I make the point about each process having multiple PIDs"
Quoted 3 lines
man2/clone.2 in the same · line 322
Quoted 3 lines
man2/clone.2 +3
-0+The existence of a namespace hierarchy means that each process +may now have multiple PIDs: +one for each namespace in which it is visible.I added some words here:
"each of these PIDs is unique within the corresponding namespace".
Correct.
Thanks for the ACK.
Quoted 7 lines
Quoted 7 lines
Quoted 6 lines
man2/clone.2 in the same · line 326
Quoted 4 lines
man2/clone.2 +4
-0+(A call to +.BR getpid (2) +always returns the PID associated with the namespace in which +the process was created.)I don't thinks it's a good example - the getpid cannot be called for other process other than current :)
Quoted 8 lines
Quoted 5 lines
It wasn't meant as an example. The point was, with a process potentially being a member of multiple namespaces, the reader might
wonder: what does getpid(2) return? This sentence was intended to clarify that. With that explanation, does this sentence now seem okay?Yes, but I'd change "was created" into "lives in". From my POV this sounds more clear. I do not insist however :)
Done.
Thanks,
Michael
Signature · 5 lines
Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ git://git.kernel.org/pub/scm/docs/man-pages/man-pages.git man-pages online: http://www.kernel.org/doc/man-pages/online_pages.html Found a bug? http://www.kernel.org/doc/man-pages/reporting_bugs.html