CLONE_NEWIPC documentation

CLONE_NEWIPC documentation

[Michael Kerrisk]

Kirill, Pavel,

Below is a patch to document the CLONE_NEWIPC flag that was
added in 2.6.19.

Could you please review and let me know of improvements
or inaccuracies?

Cheers,

Michael

--- a/man2/clone.2
+++ b/man2/clone.2
@@ -225,6 +224,36 @@ Calls to
 .BR umask (2)
 performed later by one of the processes do not affect the other process.
 .TP
+.BR CLONE_NEWIPC " (since Linux 2.4.19)"
+If
+.B CLONE_NEWIPC
+is set, then create the process in a new IPC namespace.
+If this flag is not set, then (as with
+.BR fork (2)),
+the process is created in the same IPC namespace as
+the calling process.
+This flag is intended for the implementation of control groups.
+
+An IPC namespace consistes of the set of identifiers for
+System V IPC objects.
+(These objects are created using
+.BR msgctl (2),
+.BR semctl (2),
+and
+.BR shmctl (2)).
+Objects created in an IPC namespace are visible to other processes
+that are members of that namespace,
+but are not visible to processes in other IPC namespaces.
+
+Use of this flag requires: a kernel configured with the
+.B CONFIG_SYSVIPC
+and
+.B CONFIG_IPC_NS
+configuration options and that the process be privileged
+.RB ( CAP_SYS_ADMIN ).
+This flag can't be specified in conjunction with
+.BR CLONE_SYSVSEM .
+.TP
 .BR CLONE_NEWNS " (since Linux 2.4.19)"
 Start the child in a new namespace.

@@ -729,6 +758,14 @@ were specified in
 .TP
 .B EINVAL
 Both
+.B CLONE_NEWIPC
+and
+.B CLONE_SYSVSEM
+were specified in
+.IR flags .
+.TP
+.B EINVAL
+Both
 .BR CLONE_NEWPID
 and
 .BR CLONE_THREAD
@@ -742,6 +779,16 @@ when a zero value is specified for
 .IR child_stack .
 .TP
 .B EINVAL
+.BR CLONE_NEWIPC
+was specified in
+.IR flags ,
+but the kernel was not configured with the
+.B CONFIG_SYSVIPC
+and
+.BR CONFIG_IPC_NS
+options.
+.TP
+.B EINVAL
 .BR CLONE_NEWPID
 was specified in
 .IR flags ,

Re: CLONE_NEWIPC documentation

[Eric W. Biederman]

Michael Kerrisk <mtk.manpages@googlemail.com> writes:

> Kirill, Pavel,
>
> Below is a patch to document the CLONE_NEWIPC flag that was
> added in 2.6.19.
>
> Could you please review and let me know of improvements
> or inaccuracies?
>
> Cheers,
>
> Michael
>
> --- a/man2/clone.2
> +++ b/man2/clone.2
> @@ -225,6 +224,36 @@ Calls to
>  .BR umask (2)
>  performed later by one of the processes do not affect the other process.
>  .TP
> +.BR CLONE_NEWIPC " (since Linux 2.4.19)"
> +If
> +.B CLONE_NEWIPC
> +is set, then create the process in a new IPC namespace.
> +If this flag is not set, then (as with
> +.BR fork (2)),
> +the process is created in the same IPC namespace as
> +the calling process.

> +This flag is intended for the implementation of control groups.

The above sentence is wrong.

+This flag is intended for the implementation of containers.

Would be correct.

Both control groups and namespaces feed into the user space container
concept.  Control groups are multiprocess resource limits.
Namespaces are affect the mapping from resource name to resource.

What is interesting is you can unshare a sysvipc namespace and still have
sysvipc shared memory mapped from another sysvipc namespace.

This is something that needs to be watched for.

Eric

Re: CLONE_NEWIPC documentation

[Cedric Le Goater]

Eric W. Biederman wrote:
> Michael Kerrisk <mtk.manpages@googlemail.com> writes:
> 
>> Kirill, Pavel,
>>
>> Below is a patch to document the CLONE_NEWIPC flag that was
>> added in 2.6.19.
>>
>> Could you please review and let me know of improvements
>> or inaccuracies?

I would also add that an interesting effect of the sysvipc namespace is
the automatic cleanup of sysvipc objects when the namespace is destroyed.

Thanks 

C.

Re: CLONE_NEWIPC documentation

[Michael Kerrisk]

Cedric,

On Thu, Nov 20, 2008 at 3:36 AM, Cedric Le Goater <clg@fr.ibm.com> wrote:
> Eric W. Biederman wrote:
>> Michael Kerrisk <mtk.manpages@googlemail.com> writes:
>>
>>> Kirill, Pavel,
>>>
>>> Below is a patch to document the CLONE_NEWIPC flag that was
>>> added in 2.6.19.
>>>
>>> Could you please review and let me know of improvements
>>> or inaccuracies?
>
> I would also add that an interesting effect of the sysvipc namespace is
> the automatic cleanup of sysvipc objects when the namespace is destroyed.

And the namespace is destroyed, when the last proces in the namespace
terminates, right?

Cheers,

Michael

-- 
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

Re: CLONE_NEWIPC documentation

[Cedric Le Goater]

Michael Kerrisk wrote:
> Cedric,
> 
> On Thu, Nov 20, 2008 at 3:36 AM, Cedric Le Goater <clg@fr.ibm.com> wrote:
>> Eric W. Biederman wrote:
>>> Michael Kerrisk <mtk.manpages@googlemail.com> writes:
>>>
>>>> Kirill, Pavel,
>>>>
>>>> Below is a patch to document the CLONE_NEWIPC flag that was
>>>> added in 2.6.19.
>>>>
>>>> Could you please review and let me know of improvements
>>>> or inaccuracies?
>> I would also add that an interesting effect of the sysvipc namespace is
>> the automatic cleanup of sysvipc objects when the namespace is destroyed.
> 
> And the namespace is destroyed, when the last proces in the namespace
> terminates, right?

exactly.

Thanks,

C.

Re: CLONE_NEWIPC documentation

[Michael Kerrisk]

On Thu, Nov 20, 2008 at 7:26 AM, Cedric Le Goater <clg@fr.ibm.com> wrote:
> Michael Kerrisk wrote:
>> Cedric,
>>
>> On Thu, Nov 20, 2008 at 3:36 AM, Cedric Le Goater <clg@fr.ibm.com> wrote:
>>> Eric W. Biederman wrote:
>>>> Michael Kerrisk <mtk.manpages@googlemail.com> writes:
>>>>
>>>>> Kirill, Pavel,
>>>>>
>>>>> Below is a patch to document the CLONE_NEWIPC flag that was
>>>>> added in 2.6.19.
>>>>>
>>>>> Could you please review and let me know of improvements
>>>>> or inaccuracies?
>>> I would also add that an interesting effect of the sysvipc namespace is
>>> the automatic cleanup of sysvipc objects when the namespace is destroyed.
>>
>> And the namespace is destroyed, when the last proces in the namespace
>> terminates, right?
>
> exactly.

Thanks Cedric.  I've added that point to the documentation.

Cheers,

Michael


-- 
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

Re: CLONE_NEWIPC documentation

[Serge E. Hallyn]

Quoting Eric W. Biederman (ebiederm@xmission.com):
> > +This flag is intended for the implementation of control groups.
> 
> The above sentence is wrong.
> 
> +This flag is intended for the implementation of containers.
> 
> Would be correct.
> 
> Both control groups and namespaces feed into the user space container
> concept.  Control groups are multiprocess resource limits.
> Namespaces are affect the mapping from resource name to resource.
> 
> What is interesting is you can unshare a sysvipc namespace and still have
> sysvipc shared memory mapped from another sysvipc namespace.
> 
> This is something that needs to be watched for.

Oh, I see, so please disregard my last msg, it seems Eric was plenty
clear.

thanks,
-serge

Re: CLONE_NEWIPC documentation

[Michael Kerrisk]

Eric W. Biederman wrote:
> Michael Kerrisk <mtk-manpages@gmx.net> writes:
> 
>> Hello Kirill,
>>
>> In 2.6.19, your patch to add support for CLONE_NEWIPC was included.  Is
>> there there some for-userland-programmers documentation of this flag
>> somewhere?  Would you be able to send some documentation to me (ideally as
>> a patch to the clone.2 man page, but otherwise some plain text will do).
>>
>> If this flag is also supported for unshare(), then could you please send me
>> a patch/text for that too?
> 
> In case someone else doesn't do better here is a short summary.

Thanks Eric.  That looks to cover a lot of the essentials.  Anyone else see
something important that should be documented?

And a further question: is CLONE_NEWIPC implemented for unshare()?

Cheers,

Michael


> CLONE_NEWIPC creates a new ipc namespace for the new child and all
> of it's children.  So far CAP_SYS_ADMIN is required.
> 
> An IPC namespace creates a new context for looking up and listing
> SYSV IPC shared memory, message queues, and semaphores.  Only allowing
> finding of SYSV IPC objects in this namespace.
> 
> For most practical purposes two processes in different SYSV IPC
> namespaces might as well be on different machines.  As they cannot
> find each others SYSV IPC resources, and so cannot interact with
> each other that way.
> 
> The implementation is essentially just a lookup of the objects
> in a different table when doing name to object translation so
> there should be no measurable overhead.
> 
> When the last process in a SYSV IPC namespace exits any remaining
> objects in that SYSV IPC namespace are destroyed.
> 
> Eric
> 

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7

Want to help with man page maintenance?  Grab the latest tarball at
http://www.kernel.org/pub/linux/docs/manpages/
read the HOWTOHELP file and grep the source files for 'FIXME'.

Re: CLONE_NEWIPC documentation

[Eric W. Biederman]

Michael Kerrisk <mtk-manpages@gmx.net> writes:

> Hello Kirill,
>
> In 2.6.19, your patch to add support for CLONE_NEWIPC was included.  Is
> there there some for-userland-programmers documentation of this flag
> somewhere?  Would you be able to send some documentation to me (ideally as
> a patch to the clone.2 man page, but otherwise some plain text will do).
>
> If this flag is also supported for unshare(), then could you please send me
> a patch/text for that too?

In case someone else doesn't do better here is a short summary.

CLONE_NEWIPC creates a new ipc namespace for the new child and all
of it's children.  So far CAP_SYS_ADMIN is required.

An IPC namespace creates a new context for looking up and listing
SYSV IPC shared memory, message queues, and semaphores.  Only allowing
finding of SYSV IPC objects in this namespace.

For most practical purposes two processes in different SYSV IPC
namespaces might as well be on different machines.  As they cannot
find each others SYSV IPC resources, and so cannot interact with
each other that way.

The implementation is essentially just a lookup of the objects
in a different table when doing name to object translation so
there should be no measurable overhead.

When the last process in a SYSV IPC namespace exits any remaining
objects in that SYSV IPC namespace are destroyed.

Eric

CLONE_NEWIPC documentation

[Michael Kerrisk]

Hello Kirill,

In 2.6.19, your patch to add support for CLONE_NEWIPC was included.  Is
there there some for-userland-programmers documentation of this flag
somewhere?  Would you be able to send some documentation to me (ideally as
a patch to the clone.2 man page, but otherwise some plain text will do).

If this flag is also supported for unshare(), then could you please send me
a patch/text for that too?

Cheers,

Michael

-- 
Michael Kerrisk
maintainer of Linux man pages Sections 2, 3, 4, 5, and 7

Want to help with man page maintenance?  Grab the latest tarball at
http://www.kernel.org/pub/linux/docs/manpages/
read the HOWTOHELP file and grep the source files for 'FIXME'.